Express Checkout Pagamento Simples – Integração Rápida

Índice

  1. Criar conta PayPal de produção
  2. Criar conta PayPal de Sandbox
    1. Criando contas de teste
    2. Obtendo as credenciais de API de teste
  3. Fluxo de integração com Express Checkout
    1. Chamada SetExpressCheckout
    2. Resposta SetExpressCheckout
    3. Chamada GetExpressCheckoutDetails
    4. Resposta GetExpressCheckoutDetails
    5. Chamada DoExpressCheckoutPayment
    6. Resposta DoExpressCheckoutPayment
  4. Tratamento de erros
  5. Ferramentas e documentações
  6. Indo para produção
    1. Criando as credenciais de produção

1. Criar conta PayPal de produção

Você já tem uma conta PayPal? Hum… Se você ainda não tem, você terá de criar uma agora. Se já possuí, pode pular para o item 2.

É necessário ter uma conta PayPal para ter acesso ao nosso ambiente de homologação e testes, que chamamos de Sandbox (guarde este nome).

  1. Acesse o link Crie sua conta do PayPal;
  2. Em país ou região, selecione Brasil;
  3. Escolha o tipo de conta: Para você ou Para sua Empresa;
  4. Preencha o formulário com os dados solicitados;

Após o preenchimento do formulário, será necessário confirmar o email da sua conta. O sistema PayPal enviará um link para validação no email cadastrado.

Atenção: Caso você esteja desenvolvendo para um cliente, empresa ou terceiros, você deve solicitar ao mesmo a criação de uma conta. E ele deverá realizar essa mesma validação. Sem isso ele não estará apto a receber pagamentos. Separe a sua conta da conta do seu cliente, empresa ou terceiros.

Atenção: Use um email genérico ao criar a conta de produção. Evite utilizar emails pessoais, mesmo que dos sócios da empresa, para criar esse tipo de conta.


2. Criar conta PayPal de Sandbox

Okay! Nesse momento, já temos uma conta PayPal de produção. E agora?

O PayPal Sandbox é uma cópia do ambiente de produção. Como uma Matrix. Os clientes, vendedores, o dinheiro, tudo é fictício. Isso significa que podemos fazer quantas transações de testes forem necessários, sem peso na consciência e sem risco de manipularmos cartão ou dinheiro de verdade.

Tudo o que precisamos fazer, é acessar o PayPal Developer e clicar no botão Login. Ao clicar no botão Login, uma janela vai abrir. Basta informar as credenciais da sua conta de produção (se lembra do passo acima?), para criar acessar o ambiente de Sandbox.

2.1 Criando contas de teste

  1. No menu principal, clique em Applications
  2. No menu lateral, clique em Sandbox Accounts
  3. Na tela que abriu, clique no botão azul Create Account

Apenas lembre-se de selecionar Brazil no campo country e escolher o tipo Personal para contas de clientes e Business para contas de vendedores.

Atenção: Devido as nossas leis financeiras serem diferentes de outros países, é importante você criar uma conta brasileira para utilizar no desenvolvimento e evitar problemas de funcionalidades ao colocar em produção.

2.2 Obtendo as credenciais de API de teste

Assim que terminar de preencher o formulário, você verá uma tabela com sua nova conta de teste. Se você tiver criado uma conta Business para vendedor, você pode clicar na conta que aparece na listagem e, depois, no link Profile. Uma janela como a abaixo irá se abrir:

Anote essas informações. Você precisará do usuário, senha e assinatura da API, para fazer sua primeira integração PayPal.


3. Fluxo de integração com Express Checkout

A integração com Express Checkout é feita através de três operações básicas:

1 – SetExpressCheckout – Essa operação configura a transação, definido os produtos do carrinho do cliente, valor dos itens, taxas, despesas de manipulação e frete, além do valor total da transação. Após a execução dessa operação, sua aplicação receberá um TOKEN, que deverá ser utilizado para redirecionar o cliente para o ambiente seguro da PayPal.

2 – GetExpressCheckoutDetails – Essa operação é opcional e pode ser executada em qualquer momento. Ela permitirá que sua aplicação conheça detalhes do cliente e a transação relacionada.

3 – DoExpressCheckoutPayment – Essa é a operação mais importante do fluxo de integração. É fundamental que essa operação seja executada assim que o cliente for redirecionado de volta para a loja, pois é somente através dessa operação, que uma transação vira pagamento e o valor pago pelo cliente vá para a sua conta de vendedor.

fluxo-express-checkout

3.1 Chamada SetExpressCheckout

A chamada para a operação SetExpressCheckout é feita através de uma requisição HTTP utilizando o método POST. Essa requisição deverá ser enviada para o endpoint do Sandbox https://api-3t.sandbox.paypal.com/nvp, e se parecerá com o seguinte:

POST /nvp HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: https://api-3t.sandbox.paypal.com

USER=usuário-da-api&
PWD=senha-da-api&
SIGNATURE=assinatura-da-api&

METHOD=SetExpressCheckout&
VERSION=114.0&

PAYMENTREQUEST_0_PAYMENTACTION=SALE&
PAYMENTREQUEST_0_AMT=22.00&
PAYMENTREQUEST_0_CURRENCYCODE=BRL&
PAYMENTREQUEST_0_ITEMAMT=22.00&
PAYMENTREQUEST_0_INVNUM=1234&
L_PAYMENTREQUEST_0_NAME0=Item A&
L_PAYMENTREQUEST_0_DESC0=Produto A – 110V&
L_PAYMENTREQUEST_0_AMT0=11.00&
L_PAYMENTREQUEST_0_QTY0=1&
L_PAYMENTREQUEST_0_ITEMAMT=11.00&
L_PAYMENTREQUEST_0_NAME1=Item B&
L_PAYMENTREQUEST_0_DESC1=Produto B – 220V&
L_PAYMENTREQUEST_0_AMT1=11.00&
L_PAYMENTREQUEST_0_QTY1=1&

RETURNURL=http://loja.com.br/retorno&
CANCELURL=http://loja.com.br/cancelamento&

BUTTONSOURCE=BR_EC_EMPRESA&
SUBJECT=conta@vendedor.com.br

Para saber o detalhe de cada campo e os valores aceitos acesse nosso guia completo (em inglês): SetExpressCheckout API Operation (NVP)

3.2 Resposta SetExpressCheckout

Ao enviar a requisição da operação SetExpressCheckout, você receberá como resposta o seguinte:

TOKEN=EC-7UB01228PL2085210&
TIMESTAMP=2014-07-15T17:00:29Z&
CORRELATIONID=690ae1f2dccd8&
ACK=Success&
VERSION=108.0&
BUILD=11843215&

Veja que o primeiro campo da resposta, é o TOKEN. Utilize o valor desse campo, para redirecionar o cliente para a página segura de pagamento PayPal: https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token={TOKEN}

3.3 Chamada GetExpressCheckoutDetails

A operação GetExpressCheckoutDetails pode ser executada a qualquer momento, enquanto o TOKEN recebido na resposta do SetExpressCheckout for válido. O TOKEN, além das credenciais, é o único parâmetro requerido na operação GetExpressCheckoutDetails.

POST /nvp HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: https://api-3t.sandbox.paypal.com

USER=usuário-da-api&
PWD=senha-da-api&
SIGNATURE=assinatura-da-api&
VERSION=114.0&
METHOD=GetExpressCheckoutDetails&
TOKEN=EC-7UB01228PL2085210

Para saber o detalhe de cada campo e os valores aceitos acesse nosso guia completo (em inglês): GetExpressCheckoutDetails API Operation (NVP)

3.4 Resposta GetExpressCheckoutDetails

Atenção: Pode acontecer de o cliente ainda não ter autorizado o pagamento na página da PayPal, ou de você ainda não ter executado a operação DoExpressCheckoutPayment. Nesse caso, você verá que o campo CHECKOUTSTATUS terá o valor PaymentActionNotInitiated, que significa exatamente isso.

TOKEN=EC-7UB01228PL2085210&
BILLINGAGREEMENTACCEPTEDSTATUS=0&
CHECKOUTSTATUS=PaymentActionNotInitiated&
TIMESTAMP=2014-07-15T17:53:43Z&
CORRELATIONID=155e58baae7a&
ACK=Success&
VERSION=108.0&
BUILD=11843215&
CURRENCYCODE=BRL&
AMT=22.00&
ITEMAMT=22.00&
SHIPPINGAMT=0.00&
HANDLINGAMT=0.00&
TAXAMT=0.00&
INVNUM=12345&
INSURANCEAMT=0.00&
SHIPDISCAMT=0.00&
L_NAME0=Item A&
L_NAME1=Item B&
L_QTY0=1&
L_QTY1=1&
L_TAXAMT0=0.00&
L_TAXAMT1=0.00&
L_AMT0=11.00&
L_AMT1=11.00&
L_DESC0=Produto A – 110V&
L_DESC1=Produto B – 220V&
L_ITEMWEIGHTVALUE0=   0.00000&
L_ITEMWEIGHTVALUE1=   0.00000&
L_ITEMLENGTHVALUE0=   0.00000&
L_ITEMLENGTHVALUE1=   0.00000&
L_ITEMWIDTHVALUE0=   0.00000&
L_ITEMWIDTHVALUE1=   0.00000&
L_ITEMHEIGHTVALUE0=   0.00000&
L_ITEMHEIGHTVALUE1=   0.00000&
PAYMENTREQUEST_0_CURRENCYCODE=BRL&
PAYMENTREQUEST_0_AMT=22.00&
PAYMENTREQUEST_0_ITEMAMT=22.00&
PAYMENTREQUEST_0_SHIPPINGAMT=0.00&
PAYMENTREQUEST_0_HANDLINGAMT=0.00&
PAYMENTREQUEST_0_TAXAMT=0.00&
PAYMENTREQUEST_0_INVNUM=12345&
PAYMENTREQUEST_0_INSURANCEAMT=0.00&
PAYMENTREQUEST_0_SHIPDISCAMT=0.00&
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED=false&
PAYMENTREQUEST_0_ADDRESSNORMALIZATIONSTATUS=None&
L_PAYMENTREQUEST_0_NAME0=Item A&
L_PAYMENTREQUEST_0_NAME1=Item B&
L_PAYMENTREQUEST_0_QTY0=1&
L_PAYMENTREQUEST_0_QTY1=1&
L_PAYMENTREQUEST_0_TAXAMT0=0.00&
L_PAYMENTREQUEST_0_TAXAMT1=0.00&
L_PAYMENTREQUEST_0_AMT0=11.00&
L_PAYMENTREQUEST_0_AMT1=11.00&
L_PAYMENTREQUEST_0_DESC0=Produto A – 110V&
L_PAYMENTREQUEST_0_DESC1=Produto B – 220V&
L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE0=   0.00000&
L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE1=   0.00000&
L_PAYMENTREQUEST_0_ITEMLENGTHVALUE0=   0.00000&
L_PAYMENTREQUEST_0_ITEMLENGTHVALUE1=   0.00000&
L_PAYMENTREQUEST_0_ITEMWIDTHVALUE0=   0.00000&
L_PAYMENTREQUEST_0_ITEMWIDTHVALUE1=   0.00000&
L_PAYMENTREQUEST_0_ITEMHEIGHTVALUE0=   0.00000&
L_PAYMENTREQUEST_0_ITEMHEIGHTVALUE1=   0.00000&
PAYMENTREQUESTINFO_0_ERRORCODE=0&

Atenção: Um detalhe importante, é o campo ACK. Perceba que ele estará presente tanto na resposta do SetExpressCheckout, quanto do GetExpressCheckoutDetails e do DoExpressCheckoutPayment. Quando o valor do ACK for Success, significa que o servidor da API PayPal compreendeu sua requisição, ou seja, você a enviou corretamente e pode seguir com o fluxo de integração. Esse campo não significa o sucesso da transação, nem que o cliente fez o pagamento. Significa apenas que o servidor entendeu sua requisição.

3.5 Chamada DoExpressCheckoutPayment

A operação DoExpressCheckoutPayment é a mais importante de todo o fluxo. É o DoExpressCheckoutPayment que transforma a sessão em transação de pagamento. É através dessa operação que o cliente é cobrado e o pagamento vai para a conta do vendedor.

POST /nvp HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: https://api-3t.sandbox.paypal.com

USER=usuário-da-api&
PWD=senha-da-api&
SIGNATURE=assinatura-da-api&
VERSION=114.0&
METHOD=DoExpressCheckoutPayment&
TOKEN=EC-7UB01228PL2085210&
PAYERID=A4XNCZE66U85Y&
PAYMENTREQUEST_0_PAYMENTACTION=SALE&
PAYMENTREQUEST_0_AMT=22.00&
PAYMENTREQUEST_0_CURRENCYCODE=BRL&
PAYMENTREQUEST_0_ITEMAMT=22.00&
PAYMENTREQUEST_0_INVNUM=12345&
L_PAYMENTREQUEST_0_NAME0=Item A&
L_PAYMENTREQUEST_0_DESC0=Produto A – 110V&
L_PAYMENTREQUEST_0_AMT0=11.00&
L_PAYMENTREQUEST_0_QTY0=1&
L_PAYMENTREQUEST_0_ITEMAMT=11.00&
L_PAYMENTREQUEST_0_NAME1=Item B&
L_PAYMENTREQUEST_0_DESC1=Produto B – 220V&
L_PAYMENTREQUEST_0_AMT1=11.00&
L_PAYMENTREQUEST_0_QTY1=1&

Para saber o detalhe de cada campo e os valores aceitos acesse nosso guia completo (em inglês): DoExpressCheckoutPayment API Operation (NVP)

3.6 Resposta DoExpressCheckoutPayment

A reposta do DoExpressCheckoutPayment vai retornar, entre outros campos, o PAYMENTINFO_n_TRANSACTIONID. Esse campo deve ser armazenado em sua base de dados, para acompanhamento futuro. O campo que vai informar o estado da transação, é o campo PAYMENTINFO_n_PAYMENTSTATUS. Para conhecer os estados da transação e como tratá-los, veja nosso Guia de integração com Express Checkout.

Outros campos que você deve ficar atento, são PAYMENTINFO_n_PENDINGREASON e PAYMENTINFO_n_REASONCODE. Caso a transação não tenha sido aprovada ainda e tenha ido para revisão, esses dois campos irão informar sobre o motivo.

Para ter direito à proteção ao vendedor, a mercadoria deve ser entregue no endereço retornado pela operação GetExpressCheckoutDetails.

Atenção: Como esse endereço pode ser modificado pelo cliente na tela de checkout PayPal, recomendamos que a operação GetExpressCheckoutDetails seja executada logo após a execução da operação DoExpressCheckoutPayment.

TOKEN=EC-7UB01228PL2085210&
SUCCESSPAGEREDIRECTREQUESTED=false&
TIMESTAMP=2014-07-15T18:21:33Z&
CORRELATIONID=a48361192f80f&
ACK=Success&
VERSION=108.0&
BUILD=11843215&
INSURANCEOPTIONSELECTED=false&
SHIPPINGOPTIONISDEFAULT=false&
PAYMENTINFO_0_TRANSACTIONID=08D78639E58604008&
PAYMENTINFO_0_TRANSACTIONTYPE=cart&
PAYMENTINFO_0_PAYMENTTYPE=instant&
PAYMENTINFO_0_ORDERTIME=2014-07-15T18:21:32Z&
PAYMENTINFO_0_AMT=22.00&
PAYMENTINFO_0_FEEAMT=1.26&
PAYMENTINFO_0_SETTLEAMT=8.84&
PAYMENTINFO_0_TAXAMT=0.00&
PAYMENTINFO_0_CURRENCYCODE=BRL&
PAYMENTINFO_0_EXCHANGERATE=0.426354&
PAYMENTINFO_0_PAYMENTSTATUS=Completed&
PAYMENTINFO_0_PENDINGREASON=None&
PAYMENTINFO_0_REASONCODE=None&
PAYMENTINFO_0_PROTECTIONELIGIBILITY=Eligible&
PAYMENTINFO_0_PROTECTIONELIGIBILITYTYPE=ItemNotReceivedEligible,UnauthorizedPaymentEligible&
PAYMENTINFO_0_SECUREMERCHANTACCOUNTID=HM3KN78XEZJZC&
PAYMENTINFO_0_ERRORCODE=0&
PAYMENTINFO_0_ACK=Success&

4. Tratamento de erros

Durante a integração com Express Checkout, alguns erros podem ser retornados pelas operações. Abaixo, alguns erros mais comuns, o que significam e como tratá-los:

Erro 10001

O erro 10001 é um erro interno do servidor. Caso esse erro venha a ocorrer, tudo o que o desenvolvedor precisa fazer é reenviar a requisição novamente, pelo menos mais uma vez. Caso o erro volte a ocorrer, então será necessário aguardar alguns instantes, antes de enviar a requisição novamente. Esse tipo de erro é temporário e não está relacionado com o código de integração.

Erro 10486

O erro 10486 ocorre durante a execução da operação DoExpressCheckoutPayment e significa que o cartão do cliente não foi autorizado. Porém, não significa que a transação foi negada.

Caso receba esse erro durante a integração, a aplicação deverá redirecionar o cliente de volta para o ambiente de pagamento PayPal utilizando o mesmo TOKEN que utilizado anteriormente, para que o cliente escolha outra forma de pagamento.

Então, se o cliente havia sido redirecionado inicialmente utilizando a seguinte URL: https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-ABCDE12345, então a mesma URL deverá ser utilizada novamente.


5. Ferramentas e documentações

Para informações mais detalhadas sobre a integração com Express Checkout, veja os seguintes links:


6. Indo para produção

Ao terminar a integração, você precisará migrar seu código para o ambiente de produção. Para isso, será necessário atualizar as credenciais da API e os endpoints. Abaixo, um checklist de todos os itens que precisam ser verificados para migração para produção:

  1. Tenha certeza de que sua conta de produção está verificada.
  2. Gere as credenciais da API para o ambiente de produção.
  3. Atualize as credenciais da API no seu código.
  4. Atualize os endpoints da API no seu código. Abaixo, os endpoints de produção:
    • Endpoint da API – https://api-3t.paypal.com/nvp.
    • Endpoint do redirecionamento – https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&useraction=commit&token={TOKEN}.
  5. Se necessário, adicione os IPs dos servidores da PayPal na lista de servidores confiáveis em seu Firewall. A lista de IPs atualizada por ser encontrada em: IP addresses for PayPal servers.

Atenção: Os ambientes de produção e Sandbox possuem credenciais diferentes. Credenciais do Sandbox não funcionarão no ambiente de produção. Troque as credenciais no seu código e remova o sandbox de todas as URLs.

6.1 Criando as credenciais de produção

  1. Acesse o site do PayPal e faça o login;
  2. Após o login, no menu principal, clique na opção Perfil;
  3. Na nova tela, no menu lateral, clique em Minhas Ferramentas de Venda;
  4. Na listagem do lado direito, localize a opção Acesso à API e clique em Atualizar;
  5. Na nova tela, selecione a opção 2: Solicitar credenciais de Interface de Programação de Aplicativos (API);
  6. Uma nova tela será aberta. Selecione a opção Solicite uma assinatura de API e clique em Concordar e enviar.
  7. Na nova tela, copie as credenciais de acesso à API que foram exibidas e atualize seu código de integração.