Neste tutorial, demonstraremos como funcionam os pagamentos recorrentes, as diversas possibilidades e como fazer a integração utilizando PayPal Express Checkout. Ao final, demonstraremos, com alguns casos de uso, como se dá a integração em uma aplicação real, utilizando códigos de exemplo em PHP.
Este tutorial está organizado da seguinte forma:
- 1. Pagamentos Recorrentes com PayPal
- 2. Criando um perfil de Pagamento Recorrente
- 2.1 Alguns casos de uso
- 2.2 Período de experiência
- 2.3 Pagamento inicial não recorrente
- 2.4 Outros recursos
- 3. Digital Goods e pagamentos recorrentes
- 4. PayPal Express Checkout com pagamentos recorrentes
- 4.1 Fluxo do Express Checkout
- 4.2 Configurando o Express Checkout
- 4.2.1 Exemplos de requisição e resposta
- 5. Modificando um perfil de pagamento recorrente
- 5.1 Atualizações de endereço
- 5.2 Atualizações no valor do pagamento
- 5.3 ampos requeridos para a operação UpdateRecurringPaymentsProfile
- 5.3.1 Exemplos de requisição e resposta
- 6. Aplicação de exemplo
- 6.1 Criação do perfil de pagamento recorrente
- 6.2 Gerenciamento do perfil de pagamento recorrente
- 6.3 Negociação e descontos
- 7. Outras referências
Pagamentos Recorrentes com PayPal
Existem duas formas de se criar pagamentos recorrentes com PayPal. A primeira, mais simples porém mais limitada, é utilizando o botão “Assinatura” do PayPal Website Payments Standard. A segunda, que oferece mais recursos, é utilizando PayPal Express Checkout, que veremos nesse artigo.
Os pagamentos recorrentes são criados através de um perfil, que contém informações sobre o pagamento, sua recorrência, período de teste (trial) e o período regular. Tanto o período de teste, quanto o período regular, possuem informações sobre valores, taxas e despesas de frete (quando aplicáveis).
Isso significa que podemos ter, por exemplo, um perfil de assinatura para uma revista, onde o cliente paga mensalmente por um produto físico que lhe será entregue, ou para a assinatura de um plano de TV, onde o cliente para mensalmente por um produto digital.
Ao utilizar a API de pagamentos recorrentes, temos algumas possibilidades interessantes, que permitem que possamos ter um painel administrativo em nossa aplicação, onde podemos ter os seguintes recursos:
- Obter informações sobre um perfil de pagamento recorrente.
- Modificar o status de um perfil de pagamento recorrente.
- Atualizar informações sobre um perfil de pagamento recorrente.
- Cobrar o montante “a pagar” de um perfil de pagamento recorrente.
- Cancelar um perfil de pagamento recorrente.
Como podemos ver, a API de pagamentos recorrentes é extremamente poderosa e nos permite ter um CRUD via API, para manipular as informações conforme nossas regras de negócio.
Criando um perfil de Pagamento Recorrente
A API para criação de perfis de pagamento recorrente é bastante flexível e adequa à diversos casos de uso. Para definir um perfil de pagamento recorrente, os seguintes campos são necessários:
- PROFILESTARTDATE – Especifica a data do início do perfil.
- BILLINGPERIOD – Periodicidade do perfil, pode ter os seguintes valores:
- Day – É um perfil de pagamento diário.
- Week – É um perfil de pagamento semanal.
- Month – É um perfil de pagamento mensal.
- Year – É um perfil de pagamento anual.
- BILLINGFREQUENCY – Especifica o número de períodos que formam 1 ciclo de pagamento, ou seja, se tivermos um BILLINGPERIOD definido como Month e BILLINGFREQUENCY definido como 3, então temos um ciclo de pagamento de 3 meses.
- AMT – O valor que será cobrado em cada ciclo de pagamento.
Além desses campos, existe ainda a possibilidade de informar o campo opcionalTOTALBILLINGCYCLES, que define o número total de ciclos de pagamento que será cobrado em todo o período regular. Ao informar o campo TOTALBILLINGCYCLES, a aplicação é capaz de definir o tempo de vida do perfil, por exemplo, se o cliente comprou a assinatura de uma revista com pagamento mensal de R$ 10, Ao definir TOTALBILLINGCYCLES com 12, estamos dizendo que o perfil de pagamento será de 1 ano, com pagamentos mensais.
Se o campo TOTALBILLINGCYCLES não for informado, o tempo de vida do perfil de pagamento recursivo será “indefinido”, ou seja, ele será válido até que o perfil seja cancelado manualmente, seja pelo cliente, ou pela loja.
Alguns casos de uso:
-
- Cliente compra a assinatura mensal de uma revista, com valor de R$ 10.00 e com validade de 1 ano. A cobrança acontecerá a cada 3 meses:
- BILLINGPERIOD = Month
- BILLINGFREQUENCY = 3
- AMT = 10.00
- TOTALBILLINGCYCLES = 4
- Isso criará um perfil de pagamento mensal, onde a cada três meses, o cliente pagará o equivalente a R$ 30,00 pela assinatura pela assinatura mensal, que terá duração de 1 ano.
-
- Cliente compra a reserva em um hotel, com valor de R$ 100.00, para 3 dias:
- BILLINGPERIOD = Day
- BILLINGFREQUENCY = 1
- AMT = 100
- TOTALBILLINGCYCLES = 3
- Isso criará um perfil de pagamento diário, onde a cada dia o cliente pagará R$ 100,00 pela hospedagem, que terá duração de 3 dias.
Existem diversas combinações possíveis, para diversos casos de uso possíveis. Essa flexibilidade faz da API de pagamentos recursivos uma ferramenta importante para N casos de uso, seja assinatura de revistas, TVs por assinatura, reservas em hoteis, assinatura de internet, provedores de conteúdo, etc.
Período de experiência
Muitas vezes, antes de adquirir uma assinatura, é comum os clientes desejarem conhecer melhor o produto que estão assinando. Muitas revistas fazem isso, oferecem uma assinatura para o cliente, mas ele ganha os primeiros 6 meses gratuitamente.
Com a API de pagamentos recorrentes, é possível oferecer, opcionalmete, um período de experiência, que é configurado de forma semelhante a configuração do perfil. Os seguintes campos são utilizados na configuração do período de experiência:
- TRIALBILLINGPERIOD – Periodicidade do período de experiência:
- Day
- Week
- Month
- Year
- TRIALBILLINGFREQUENCY – Especifica o número de períodos que formam 1 ciclo.
- TRIALAMT – Especifica o valor que será cobrado durante o período de experiência.
- TRIALTOTALBILLINGCYCLES – Especifica o número total de ciclos que terá o período de experiência. Ao contrário da criação do perfil regular, o campo TRIALTOTALBILLINGCYCLES é obrigatório.
Pagamento inicial não recorrente.
Além da definição do perfil de pagamento recorrente e do período de experiência, podemos definir um pagamento que deverá ser efetuado no momento da criação do perfil. Esse pagamento é especialmente interessante em diversos casos, como aqueles em que é cobrado pela adesão.
Um aspecto interessante desse pagamento é que, se o pagamento falhar (ex: não for aprovado pelo cartão do cliente), é possível especificar a ação que deverá ser tomada. Dois campos são necessários para especificar esse pagamento inicial:
- INITAMT – Valor inicial que deverá ser cobrado.
- FAILEDINITAMTACTION – A ação que deverá ser tomada, caso o pagamento inicial falhe. Esse campo pode receber os seguintes valores:
- ContinueOnFailure – Caso o pagamento falhe, o perfil de pagamento recorrente será criado e o valor inicial será colocado no montante a pagar do perfil.
- CancelOnFailure – Caso o pagamento inicial falhe, o perfil de pagamento recorrente não será criado.
Outros recursos
Além dos recursos descritos anteriormente, podemos ter algumas configurações para o PayPal Express Checkout referentes aos pagamentos recorrentes:
- MAXFAILEDPAYMENTS – Ao definir o campo MAXFAILEDPAYMENTS, podemos especificar um número máximo de pagamentos que “podem falhar”, antes do perfil ser cancelado automaticamente. Supondo que o campo MAXFAILEDPAYMENTS tenha sido definido com o número 3, se houverem 3 falhas de pagamento, uma mensagem IPN será enviada para a aplicação, avisando que o número de falhas de pagamento chegou ao limite e o perfil será suspenso automaticamente.
- AUTOBILLAMT – Ao definir o campo AUTOBILLAMT, o PayPal será instruído a cobrar automaticamente o “montante a pagar” no próximo ciclo. Sempre que um pagamento recorrente, ou o pagamento inicial, falha, o valor que deveria ser cobrado é adicionado em um montante a pagar. Definindo o AUTOBILLAMT, esse montante será cobrado do cliente no próximo ciclo de pagamento.
Digital Goods e pagamentos recorrentes
Como mencionado anteriormente, existem casos onde o produto não é tangível, como por exemplo a assinatura em um portal de conteúdo, onde ao assinar, o cliente tem direito ao conteúdo oferecido pelo portal. Sempre que estamos vendendo produtos intangíveis, ou seja, aqueles produtos que serão consumidos de forma digital, sem que haja a entrega ou negociação de um produto físico, podemos fazer a integração informando que se trata de um Digital Good, ou produto digital, permitindo que a negociação seja beneficiada com taxas especiais para esse tipo de produto.
A definição de um produto digital para pagamentos recorrentes segue as mesmas regras e formato de uma transação comum que utiliza Express Checkout. Abaixo os campos que identificam um produto digital ou físico:
- L_PAYMENTREQUEST_m_ITEMCATEGORYn – Informa a categoria do produto, pode ser Digital, para um produto digital, ou Physical, para um produto tangível.
- L_PAYMENTREQUEST_m_NAMEn – Informa o nome do produto.
- L_PAYMENTREQUEST_m_AMTn – Informa o valor do produto.
- L_PAYMENTREQUEST_m_QTYn – Informa a quantidade do produto.
PayPal Express Checkout com pagamentos recorrentes.
Ao fazer a integração com PayPal Express Checkout, podemos definir entre 1 e 10 (inclusive) pagamentos. Essa característica também se aplica aos pagamentos recorrentes, ou seja, podemos ter até 10 pagamentos recorrentes configurados em uma transação, ou, podemos mesclar pagamentos recorrentes com pagamentos não recorrentes, obedecendo sempre o limite de 10 pagamentos.
Para definir esse pagamento utilizando Express Checkout, utilizamos o índice m nos camposPAYMENTREQUEST_m e L_PAYMENTREQUEST_m, com índice inicial sendo 0 e máximo sendo 9. Cada PAYMENTREQUEST_m pode ter suas próprias configurações, permitindo que tenhamos oPAYMENTREQUEST_0 para um produto físico sem pagamento recorrente, e o PAYMENTREQUEST_1para um produto digital e pagamento recorrente.
Fluxo do Express Checkout
- 1. O cliente decide pagar com PayPal.
- 2. A aplicação utiliza a operação setExpressCheckout para configurar o Express Checkout.
- 3. O PayPal retorna um TOKEN que é utilizado para redirecionar o cliente para o ambiente seguro do PayPal.
- 4. O cliente faz login ou cria uma conta no PayPal.
- 5. O cliente autoriza o pagamento.
- 6. O cliente é redirecionado para a aplicação.
- 7. A aplicação utiliza a operação getExpressCheckout para obter os dados da transação e do cliente (opcional).
- 8. A aplicação utiliza a operação doExpressCheckout se houver um pagamento inicial, ou se houver a mesclagem de pagamentos não recorrentes na transação.
Se não houver um pagamento inicial ou não houver a mesclagem com pagamentos não recorrentes, essa etapa pode ser pulada. - 9. A aplicação utiliza a operação CreateRecurringPaymentProfile para criar o perfil de pagamento recorrente.
- 10. A aplicação avisa ao usuário se a operação foi bem sucedida, ou não.
Configurando o Express Checkout
Para configurar um pagamento recorrente com Express Checkout, passo 2 do fluxo descrito acima, utilizamos a operação setExpressCheckout. Além dos campos que normalmente utilizamos na operação setExpressCheckout, temos 3 campos específicos para configurar um pagamento recorrente:
Exemplo de requisição em PHP:
<?php
$curl = curl_init();curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array( 'USER' => 'neto_1306507007_biz_api1.gmail.com', 'PWD' => '1306507019', 'SIGNATURE' => 'Al8n1.tt9Sniswt8UZvcamFvsXYEAegNpyX63HRdtqJVff7rESMSQ3qN', 'METHOD' => 'SetExpressCheckout', 'VERSION' => '91', 'LOCALECODE' => 'pt_BR', 'PAYMENTREQUEST_0_AMT' => 100, 'PAYMENTREQUEST_0_CURRENCYCODE' => 'BRL', 'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale', 'PAYMENTREQUEST_0_ITEMAMT' => 100, 'L_PAYMENTREQUEST_0_NAME0' => 'Exemplo', 'L_PAYMENTREQUEST_0_DESC0' => 'Assinatura de exemplo', 'L_PAYMENTREQUEST_0_QTY0' => 1, 'L_PAYMENTREQUEST_0_AMT0' => 100, 'L_PAYMENTREQUEST_0_ITEMCATEGORY0' => 'Digital', 'L_BILLINGTYPE0' => 'RecurringPayments', 'L_BILLINGAGREEMENTDESCRIPTION0' => 'Exemplo',)));$response = curl_exec($curl);curl_close($curl);$nvp = array();if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) { foreach ($matches['name'] as $offset => $name) { $nvp[$name] = urldecode($matches['value'][$offset]); }}print_r($nvp);Resposta Obtida:
Array
( [TOKEN] => EC-0A9774676H705661Y [TIMESTAMP] => 2012-10-08T13:11:19Z [CORRELATIONID] => aaea15b01caab [ACK] => Success [VERSION] => 91 [BUILD] => 3893058)Com o TOKEN recebido após a operação setExpressCheckout, redirecionamos o usuário para o ambiente seguro da PayPal. Assim que o usuário voltar para a aplicação, a operação GetExpressCheckoutDetails é utilizada para obter os dados da transação, PayerID, entre outros.
Exemplo de requisição em PHP:
<?php
$curl = curl_init();curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array('USER' => 'neto_1306507007_biz_api1.gmail.com','PWD' => '1306507019','SIGNATURE' => 'Al8n1.tt9Sniswt8UZvcamFvsXYEAegNpyX63HRdtqJVff7rESMSQ3qN','METHOD' => 'GetExpressCheckoutDetails','VERSION' => '91','TOKEN' => 'EC-0A9774676H705661Y')));$response = curl_exec($curl);curl_close($curl);$nvp = array();if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) { foreach ($matches['name'] as $offset => $name) { $nvp[$name] = urldecode($matches['value'][$offset]); }}print_r($nvp);Resposta Obtida:
Array
( [TOKEN] => EC-0A9774676H705661Y [BILLINGAGREEMENTACCEPTEDSTATUS] => 1 [CHECKOUTSTATUS] => PaymentActionNotInitiated [TIMESTAMP] => 2012-10-08T13:24:50Z [CORRELATIONID] => 37ed3c8b9bec5 [ACK] => Success [VERSION] => 91 [BUILD] => 3893058 [EMAIL] => neto.j_1324471857_biz@gmail.com [PAYERID] => 5KWXTCEDXPFQS [PAYERSTATUS] => verified [BUSINESS] => João Batista Neto's Test Store [FIRSTNAME] => João Batista [LASTNAME] => Neto [COUNTRYCODE] => US [SHIPTONAME] => João Batista Neto's Test Store [SHIPTOSTREET] => 1 Main St [SHIPTOCITY] => San Jose [SHIPTOSTATE] => CA [SHIPTOZIP] => 95131 [SHIPTOCOUNTRYCODE] => US [SHIPTOCOUNTRYNAME] => United States [ADDRESSSTATUS] => Confirmed [CURRENCYCODE] => BRL [AMT] => 100.00 [ITEMAMT] => 100.00 [SHIPPINGAMT] => 0.00 [HANDLINGAMT] => 0.00 [TAXAMT] => 0.00 [INSURANCEAMT] => 0.00 [SHIPDISCAMT] => 0.00 [L_NAME0] => Exemplo [L_QTY0] => 1 [L_TAXAMT0] => 0.00 [L_AMT0] => 100.00 [L_DESC0] => Assinatura de exemplo [L_ITEMWEIGHTVALUE0] => 0.00000 [L_ITEMLENGTHVALUE0] => 0.00000 [L_ITEMWIDTHVALUE0] => 0.00000 [L_ITEMHEIGHTVALUE0] => 0.00000 [L_ITEMCATEGORY0] => Digital [PAYMENTREQUEST_0_CURRENCYCODE] => BRL [PAYMENTREQUEST_0_AMT] => 100.00 [PAYMENTREQUEST_0_ITEMAMT] => 100.00 [PAYMENTREQUEST_0_SHIPPINGAMT] => 0.00 [PAYMENTREQUEST_0_HANDLINGAMT] => 0.00 [PAYMENTREQUEST_0_TAXAMT] => 0.00 [PAYMENTREQUEST_0_INSURANCEAMT] => 0.00 [PAYMENTREQUEST_0_SHIPDISCAMT] => 0.00 [PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED] => false [PAYMENTREQUEST_0_SHIPTONAME] => João Batista Neto's Test Store [PAYMENTREQUEST_0_SHIPTOSTREET] => 1 Main St [PAYMENTREQUEST_0_SHIPTOCITY] => San Jose [PAYMENTREQUEST_0_SHIPTOSTATE] => CA [PAYMENTREQUEST_0_SHIPTOZIP] => 95131 [PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE] => US [PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME] => United States [PAYMENTREQUEST_0_ADDRESSSTATUS] => Confirmed [L_PAYMENTREQUEST_0_NAME0] => Exemplo [L_PAYMENTREQUEST_0_QTY0] => 1 [L_PAYMENTREQUEST_0_TAXAMT0] => 0.00 [L_PAYMENTREQUEST_0_AMT0] => 100.00 [L_PAYMENTREQUEST_0_DESC0] => Assinatura de exemplo [L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE0] => 0.00000 [L_PAYMENTREQUEST_0_ITEMLENGTHVALUE0] => 0.00000 [L_PAYMENTREQUEST_0_ITEMWIDTHVALUE0] => 0.00000 [L_PAYMENTREQUEST_0_ITEMHEIGHTVALUE0] => 0.00000 [L_PAYMENTREQUEST_0_ITEMCATEGORY0] => Digital [PAYMENTREQUESTINFO_0_ERRORCODE] => 0)Com o TOKEN e o PayerID, recebido após a execução da operação GetExpressCheckoutDetails, podemos criar o perfil de pagamento recorrente utilizando a operaçãoCreateRecurringPaymentsProfile:
Exemplo de requisição em PHP:
<?php
$curl = curl_init();curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array( 'USER' => 'neto_1306507007_biz_api1.gmail.com', 'PWD' => '1306507019', 'SIGNATURE' => 'Al8n1.tt9Sniswt8UZvcamFvsXYEAegNpyX63HRdtqJVff7rESMSQ3qN', 'METHOD' => 'CreateRecurringPaymentsProfile', 'VERSION' => '91', 'LOCALECODE' => 'pt_BR', 'TOKEN' => 'EC-0A9774676H705661Y', 'PayerID' => '5KWXTCEDXPFQS', 'PROFILESTARTDATE' => '2012-10-08T16:00:00Z', 'DESC' => 'Exemplo', 'BILLINGPERIOD' => 'Month', 'BILLINGFREQUENCY' => '1', 'AMT' => 100, 'CURRENCYCODE' => 'BRL', 'COUNTRYCODE' => 'BR', 'MAXFAILEDPAYMENTS' => 3)));$response = curl_exec($curl);curl_close($curl);$nvp = array();if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) { foreach ($matches['name'] as $offset => $name) { $nvp[$name] = urldecode($matches['value'][$offset]); }}var_dump($nvp);Resposta obtida:
array(7) {
'PROFILEID' => string(14) "I-FYYMDB55ADSH" 'PROFILESTATUS' => string(13) "ActiveProfile" 'TIMESTAMP' => string(20) "2012-10-08T13:27:16Z" 'CORRELATIONID' => string(13) "d7105afc5e544" 'ACK' => string(7) "Success" 'VERSION' => string(2) "91" 'BUILD' => string(7) "3842185"}Modificando um perfil de pagamento recorrente
Uma situação muito comum em assinaturas, é a necessidade de mudar um perfil de pagamentos. Isso é comum, principalmente, em casos de mudanças de regras de negócio, com a inclusão de promoções, que podem fazer com que o cliente deseje atualizar sua assinatura para uma com mais recursos.
Se tomarmos como caso de uso uma TV por assinatura, o cliente pode fazer a assinatura de um plano Standard e, depois de conhecido o produto, desejar migrar para uma assinatura Gold, com mais canais. Essa migração de plano afeta diretamente o perfil de pagamentos recorrentes, uma vez que a assinatura Gold, por oferecer mais canais, tem um preço diferente.
É claro que o perfil de pagamentos recorrentes pode, sempre, ser modificado através do painel da conta do vendedor no PayPal, mas como toda a criação do perfil ocorreu via API e regras de negócio podem acontecer com certa frequência, é fundamental que tenhamos a possibilidade de fazer essa mudança via API.
Existem, contudo, algumas restrições para a modificação de um perfil de pagamentos recorrentes. Abaixo a lista dessas restrições:
- Não é possível mudar a frequência da cobrança. Se o cliente aprovou uma cobrança mensal, não é possível mudá-la para diário, ou vice-versa. Podemos, contudo, mudar o número de ciclos para cobrança, ou seja, se o cliente aprovou uma cobrança mensal, podemos redefinir o perfil para que a cobrança aconteça a cada 6 ciclos (semestralmente).
- Só é possível mudar o valor da cobrança (e outros) com, no mínimo, três dias de antecedência do agendamento do pagamento. Se houver a tentativa de mudança dentro desses três dias, um erro será retornado.
Abaixo a lista de informações do perfil que podem ser editadas:
- Nome do assinante e seu endereço.
- Montante a pagar.
- Se o montante a pagar deverá ser cobrado no próximo ciclo.
- Número máximo de falhas de pagamentos permitido.
- Descrição do perfil e transação de referência.
- Número de ciclos de cobrança adicionais.
- Valor da cobrança, taxas e despesas de entrega.
Todas as mudanças feitas em um perfil de pagamento recorrente acontecerão no próximo pagamento, após a chamada a operação.
Atualizações de endereço
Caso seja necessário atualizar o bairro do cliente, por exemplo, será necessário informar todos os campos do endereço, não apenas o bairro.
Atualizações no valor do pagamento
Existe uma restrição importante para mudanças no valor dos pagamentos. O valor pode ser acrescido em apenas 20% dentro de um período máximo de 180 dias após a criação do perfil. Nesses 20% já devem ser contabilizados despesas com entrega, taxas e outros. Tomando como caso de uso a assinatura de uma revista, se o cliente fizer uma assinatura, no dia 1 de Janeiro, com o valor de R$ 100.00, então o novo valor deverá ser de no máximo R$ 120.00, já incluindo as despesas de entrega, e essa atualização não poderá ocorrer depois do dia 29 de Junho.
Campos requeridos para a operação UpdateRecurringPaymentsProfile
Cada tipo de edição de perfil requer algum campo específico. Existem, contudo, dois campos que são requeridos para qualquer tipo de edição, que são, além dos campos de autenticação (USER, PWD e SIGNATURE):
- METHOD – Deve ser UpdateRecurringPaymentsProfile
- PROFILEID – ID do perfil de pagamento, recebido após a chamada CreateRecurringPaymentProfile.
A lista com todos os campos pode ser encontrada no seguinte link: Manual UpdateRecurringPaymentsProfile
Exemplo de requisição em PHP:
A requisição abaixo edita um perfil, mudando o valor de 100 para 120:
<?php
$curl = curl_init();curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array( 'USER' => 'neto_1306507007_biz_api1.gmail.com', 'PWD' => '1306507019', 'SIGNATURE' => 'Al8n1.tt9Sniswt8UZvcamFvsXYEAegNpyX63HRdtqJVff7rESMSQ3qN', 'METHOD' => 'UpdateRecurringPaymentsProfile', 'VERSION' => '91', 'PROFILEID' => 'I-FYYMDB55ADSH', 'NOTE' => 'Uma nota opcional, explicando o motivo da mudança', 'AMT' => 120, 'CURRENCYCODE' => 'BRL')));$response = curl_exec($curl);curl_close($curl);$nvp = array();if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) { foreach ($matches['name'] as $offset => $name) { $nvp[$name] = urldecode($matches['value'][$offset]); }}var_dump($nvp);Resposta obtida:
array(6) { 'PROFILEID' => string(14) "I-FYYMDB55ADSH" 'TIMESTAMP' => string(20) "2012-10-08T14:24:32Z" 'CORRELATIONID' => string(13) "79a27505cf021" 'ACK' => string(7) "Success" 'VERSION' => string(2) "91" 'BUILD' => string(7) "3842185"}Exemplo de requisição em PHP:
O mesmo tipo de chamada pode ser feita ao contrário, simulando um desconto.
<?php$curl = curl_init();curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array( 'USER' => 'neto_1306507007_biz_api1.gmail.com', 'PWD' => '1306507019', 'SIGNATURE' => 'Al8n1.tt9Sniswt8UZvcamFvsXYEAegNpyX63HRdtqJVff7rESMSQ3qN', 'METHOD' => 'UpdateRecurringPaymentsProfile', 'VERSION' => '91', 'PROFILEID' => 'I-FYYMDB55ADSH', 'NOTE' => 'Uma nota opcional, explicando o motivo da mudança', 'AMT' => 60, 'CURRENCYCODE' => 'BRL')));$response = curl_exec($curl);curl_close($curl);$nvp = array();if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) { foreach ($matches['name'] as $offset => $name) { $nvp[$name] = urldecode($matches['value'][$offset]); }}var_dump($nvp);Resposta obtida:
array(6) { 'PROFILEID' => string(14) "I-FYYMDB55ADSH" 'TIMESTAMP' => string(20) "2012-10-08T14:31:11Z" 'CORRELATIONID' => string(13) "bc989d151eaa7" 'ACK' => string(7) "Success" 'VERSION' => string(2) "91" 'BUILD' => string(7) "3842185"}Aplicação de exemplo
Para demonstrar a integração com a API de pagamentos recorrentes, desenvolvemos uma aplicação que ilustra um site de TV por assinatura, onde o cliente pode assinar um plano de TV. Abaixo os casos cobertos pela aplicação de demonstração:
Criação do perfil de pagamento recorrente
Para demonstrar as possibilidades do período de demonstração, teremos dois tipos de assinatura.
O primeiro tipo de assinatura garantirá um período de carência de 45 dias para o início do pagamento. Para isso, configuraremos a operação CreateRecurringPaymentsProfile da seguinte forma:
- TRIALBILLINGPERIOD – Como Day, para definir a periodicidade diária do período de experiência.
- TRIALBILLINGFREQUENCY – Como 45, para especificar que o cliente terá 45 dias de experiência.
- TRIALAMT – Esse valor será definido como 0, indicando a gratuidade durante o período de demonstração.
- TRIALTOTALBILLINGCYCLES – Como 1, para especificar que o cliente terá apenas 1 ciclo de 45 dias de experiência.
O segundo tipo garantirá um desconto nos três primeiros meses. Supondo que o valor da assinatura seja de R$ 100 por mês, durante o período de experiência, o cliente pagará apenas R$ 50. Para isso, configuraremos a operação CreateRecurringPaymentsProfile da seguinte forma:
- TRIALBILLINGPERIOD – Como Month, para definir a periodicidade mensal do período de experiência.
- TRIALBILLINGFREQUENCY – Como 1, para especificar que o pagamento acontece todo mês.
- TRIALAMT – Esse valor será definido como 50.
- TRIALTOTALBILLINGCYCLES – Como 3, para especificar que o cliente terá apenas 3 ciclos de 1 mês de experiência, ou seja, 3 meses.
Gerenciamento do perfil de pagamento recorrente
Independentemente de cancelamento ou suspensão, utilizaremos a operação ManageRecurringPaymentsProfileStatus para lidar com essa situação. Para isso, enviaremos a requisição com os seguintes campos:
- METHOD – ManageRecurringPaymentsProfileStatus
- PROFILEID – ID do perfil de pagamento recorrente que será editado.
- ACTION – A ação que será executada. Os seguintes valores são aceitos:
- Cancel – Para cancelar o perfil.
- Suspend – Para suspender o perfil.
- Reactivate – Para reativar o perfil, após uma suspensão.
- NOTE – Para adicionar uma nota opcional, que descreve o motivo da suspensão ou cancelamento.
Negociação e descontos
Para isso, enviaremos a requisição com os seguintes campos:
- METHOD – UpdateRecurringPaymentsProfile
- PROFILEID – ID do perfil de pagamento que será editado.
- AMT – Novo valor da assinatura.
- CURRENCYCODE – BRL, para definir que o valor é em real brasileiro.
- NOTE – Para adicionar uma nota opcional, que descreve o motivo da edição do perfil.
Outras referências
Abaixo, alguns links importantes, contendo a documentação completa da API de pagamentos recorrentes, assim como a operação UpdateRecurringPaymentsProfile:
- Documentação da API
- Documentação da operação UpdateRecurringPaymentsProfile
- Documentação da operação ManageRecurringPaymentsProfileStatus
Além desses links, o site PayPal X Brasil contém diversos tutoriais, assim como um fórum, onde você poderá tirar dúvidas sobre qualquer tipo de integração, com qualquer API PayPal.
De 0 a 10, o quanto você recomendaria este artigo para um amigo?