Requisição de pagamento do PagSeguro com assinatura associada usando PHP

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

1
$data['preApprovalInitialDate' ] = '2015-01-17T19:20:30.45-03:00';
1
<initialDate>2015-01-17T19:20:30.45-03:00</initialDate>

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.sTZD clique 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.

1
$data['preApprovalFinalDate'] = '2017-01-17T19:20:30.45-03:00';
1
<finalDate>2017-01-17T19:20:30.45-03:00</finalDate>

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.

1
$data['reviewURL'] = 'http://sounoob.com.br/produto1';
1
<reviewURL>http://sounoob.com.br/produto1</reviewURL>

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>

Feito isso é só enviar a requisição da mesma forma mostrada Criando requisição de pagamento via HTTP ou Criando requisição de pagamento via XML

Veja outros posts como este aqui:

Utilizando as APIs do PagSeguro e PHP – Sem utilizar a biblioteca oficial.