Agora a API de pagamentos conta com um novo “Upgrade”, que é a possibilidade de fazer uma requisição e incluir um pagamento recorrente tudo em “uma tacada só” . Para isso usaremos o que já foi descrito aqui em no tutorial para Criando requisição de pagamento via HTTP e Criando requisição de pagamento via XML será necessário apenas incluir uns dados adicionais para enviar ao PagSeguro, o resto segue do mesmo jeito.
No outro tutorial usamos array $data para enviar todos os dados, então continuaremos usar o mesmo campo para passar os dados referente a recorrência, no caso do XML criaremos uma tag e chamaremos de preApproval essa tag deverá estar dentro da tag checkout, depois incluiremos todos parâmetros lá dentro.
Primeiro vou mostrar o pedaço do código em PHP, na linha de baixo o XML, e depois a explicação, espero que fique de fácil compreensão.
1
$data['preApprovalCharge']='manual';
1
<charge>manual</charge>
A primeira coisa que se deve definir é isso, é configurar sua recorrência para cobrança manual, seria na verdade uma pré-aprovação.
1
$data['preApprovalName']='Super seguro para notebook';
1
<name>Super seguro para notebook</name>
Serve para mostrar ao comprador do que se trata a assinatura. Esse campo é obrigatório e aceita até 100 caracteres, lembrando que apesar de ser livre o PagSeguro irá remover os caracteres < (menor que) ou > (maior que) se encontrar no seu texto, então não use.
1
$data['preApprovalDetails']='Toda segunda feira será cobrado o valor de R$150,00 para o seguro do notebook';
1
<details>Toda segunda feira será cobrado o valor de R$150,00 para o seguro do notebook</details>
Mais detalhes do que é a assinatura em questão, mas cuidado para não abusar de detalhes, esse campo só aceita 255 caracteres, semelhante ao preApprovalName o PagSeguro irá remover os caracteres < (menor que) ou > (maior que).
1
$data['preApprovalAmountPerPayment']='150.00';
1
<amountPerPayment>150.00</amountPerPayment>
Valor exato de cada cobrança, como padrão do PagSeguro todos campos referente a valores deverão ser decimal com duas casas decimais separadas por ponto. Não um erro muito comum é as pessoas utilizarem virgulas o que irá resultar erro. Nesse campo você deverá passa um valor entre 1.00 e 1000000.00, qualquer coisa diferente disso poderá ocorrer erro.
1
$data['preApprovalPeriod']='WEEKLY';
1
<period>WEEKLY</period>
Um dos campos que devem ter muita atenção é esse, porque ele irá determinar qual periodicidade que a cobrança será feita, imagina você cobrar seu cliente todo ano ao invés de todo mês, então cuidado. Não preciso nem falar que esse é um campo obrigatório, afinal sem ele não dá para saber qual periodicidade será a recorrência. Nesse campo você poderá usar:
WEEKLY para toda semana;
MONTHLY para todo mês;
BIMONTHLY para a cada dois meses;
TRIMONTHLY para cada três meses;
SEMIANNUALLY a cada seis meses.
YEARLY para cada ano;
Esse é um campo case insensitive, ou seja não importa se os valores estão maiúsculo ou minusculo, o PagSeguro irá reconhece-los.
1
$data['preApprovalDayOfWeek']='MONDAY';
1
<dayOfWeek>MONDAY</dayOfWeek>
Utilize esse campo caso no parâmetro preApprovalPeriod esteja configurado como WEEKLY; Os parâmetros que podem ser passados são:
MONDAY para toda Segunda-Feira;
TUESDAY para toda Terça-Feira;
WEDNESDAY para toda Quarta-Feira;
THURSDAY para toda Quinta-Feira;
FRIDAY para toda Sexta-Feira;
SATURDAY para todo Sábado;
SUNDAY para todo Domingo;
1
$data['preApprovalDayOfMonth']=1;
1
<dayOfMonth>1</dayOfMonth>
Utilize esse campo caso no parâmetro preApprovalPeriod esteja configurado como MONTHLY, **BIMONTHLY ou TRIMONTHLY**. Nesse campo você pode enviar um valor inteiro entre 1 e 28 (Okay sua cobrança nunca poderá ocorrer dias 29, 30 ou 31. Não insista rs )
1
$data['preApprovalDayOfYear']='03-12';
1
<dayOfYear>03-12</dayOfYear>
Utilize esse campo caso no parâmetro preApprovalPeriod esteja configurado como YEARLY. Nesse campo você deve enviar o dia e mês em que ocorrerá a cobrança, lembrando que no PagSeguro primeiro vem o mês, depois o dia, seguindo o formato MM-dd
Esse é um parâmetro interessante, ele define quando que será o inicio da vigência da assinatura, assim seu sistema poderá enviar todos dados para o PagSeguro e só começar a cobrar tempos depois, será muito útil em promoções do tipo, compre agora e comece a pagar somente depois do carnaval…
Valores desse parâmetro deve seguir o formato YYYY-MM-DDThh:mm:ss.sTZDclique para ver regras veja detalhes no site W3C, lembrando que a data não deverá ser inferior a data atual, e não poderá ser superior a dois anos da data atual.
Semelhante ao parâmetro preApprovalInitialDate com diferença que este define qual será o final da vigência da assinatura, essa data obviamente deverá não ser inferior a data atual, e não poderá ser superior até dois anos da data atual. Caso o parâmetro preApprovalInitialDate foi definido o preApprovalFinalDate deverá ser superior a data definida em preApprovalInitialDate, e poderá ser superior até dois anos da preApprovalInitialDate
1
$data['preApprovalMaxAmountPerPeriod']='200.00';
1
<maxAmountPerPeriod>200.00</maxAmountPerPeriod>
Nesse parâmetro deve ser informado qual valor total máximo que o PagSeguro irá cobrar dentro do período. Esse campo deverá ser decimal com duas casas decimais separadas por ponto. Nesse campo você deverá passa um valor entre 1.00 e 2000.00.
1
$data['preApprovalMaxTotalAmount']='900.00';
1
<maxTotalAmount>900.00</maxTotalAmount>
Nesse parâmetro deve ser informado qual valor total máximo que o PagSeguro irá cobrar enquanto a assinatura for válida. Como todo campo de moeda esse deverá ser decimal com duas casas decimais separadas por ponto. Nesse campo você deverá passa um valor entre 1.00 e 35000.00.
Na documentação esse parâmetros deveria ser para informar a URL onde o usuário possa ver as regras da assinatura, mas… depois de testes eu vi que esse link aparece em: “Assinatura - alterar”, sendo assim ele possivelmente possa ser utilizado para dar outras opções ao assinante, como alteração de datas e afins…
Enfim, suponhamos que temos que criar uma assinatura com periodicidade semanal nosso array $data estaria com os seguintes campos adicionais:
1
2
3
4
5
6
7
8
9
10
11
$data['preApprovalCharge']='auto';$data['preApprovalName']='Super seguro para notebook';$data['preApprovalDetails']='Todo dia 15 será cobrado o valor de R$150,00 para o seguro do notebook';$data['preApprovalAmountPerPayment']='150.00';$data['preApprovalPeriod']='WEEKLY';$data['preApprovalDayOfWeek']='MONDAY';$data['preApprovalInitialDate']='2015-01-17T19:20:30.45+01:00';$data['preApprovalFinalDate']='2017-01-17T19:20:30.45+01:00';$data['preApprovalMaxAmountPerPeriod']='200.00';$data['preApprovalMaxTotalAmount']='900.00';$data['reviewURL']='http://sounoob.com.br/produto1';
Já o XML terá uma nova tag dentro da tab checkout chamada preApproval
1
2
3
4
5
6
7
8
9
10
11
12
13
<preApproval><charge>auto</charge><name>Super seguro para notebook</name><details>Toda segunda feira será cobrado o valor de R$150,00 para o seguro do notebook</details><amountPerPayment>150.00</amountPerPayment><period>WEEKLY</period><dayOfWeek>MONDAY</dayOfWeek><initialDate>2015-01-17T19:20:30.45-03:00</initialDate><finalDate>2017-01-17T19:20:30.45-03:00</finalDate><maxAmountPerPeriod>200.00</maxAmountPerPeriod><maxTotalAmount>900.00</maxTotalAmount><reviewURL>http://sounoob.com.br/produto1</reviewURL></preApproval>