Testando as APIs PayPal no Sandbox

O PayPal Sandbox é um ambiente isolado, que imita o ambiente de produção. Ele oferece uma forma segura de se efetuar testes de integração, sem envolvimento de contas ou dinheiro, antes de ir para produção.

Utilize o PayPal Sandbox para testar e depurar as rotinas de sua aplicação, que fazem uso das APIs PayPal.

Atenção!Este artigo é um complemento do artigo PayPal Sandbox: Ambiente e Criação de Contas. Caso ainda não tenha tido nenhum contato com o PayPal Sandbox, sugerimos que comece a leitura pelo artigo anterior.

Este guia está dividido em cinco tópicos

1 – Visão Geral

2 – Criando contas de teste

3 – Gerando as credenciais da API

4 – Fazendo chamadas da API

5 – Fazendo testes negativos

6 – Indo para produção

Visão Geral

O PayPal Sandbox espelha todos os recursos encontrados no ambiente de produção PayPal. Enquanto alguns recursos não são aplicáveis no Sandbox, como fechamento de contas, o Sandbox possui uma paridade com os recursos suportados pelas APIs no ambiente de produção. Isso significa que você pode testar sua integração PayPal e ter a certeza de o comportamento será exatamente o mesmo no ambiente de produção.

No Sandbox, as contas são fictícias. Por isso, é possível testar e depurar sua aplicação sem fazer referência a contas de usuários ou valores reais do ambiente de produção. O Sandbox permite que você teste sua integração de forma segura e permite que você implemente sua integração da melhor forma possível antes de ir para produção.

Ao inicias uma transação utilizando contas do Sandbox, a PayPal cria um mock da transação, que se comporta exatamente como uma transação no ambiente de produção. Todas as transações do Sandbox são acompanháveis no site de teste do Sandbox (https://www.sandbox.paypal.com/), exatamente como no ambiente de produção são acompanháveis no site de produção (https://www.paypal.com/).

O ambiente Sandbox

O ambiente Sandbox é composto pelo seguinte:

Durante os testes, utilize os endpoints do Sandbox e as credenciais da sua conta de teste em cada requisição que fizer. Crie e gerencie suas contas na página de contas do Developer. Utilize o site Sandbox para visualizar as transações relacionadas com suas chamadas da API.

Dica!Você pode utilizar a mesma senha em todas as contas de teste. Isso facilita na hora de acessar o site Sandbox para visualizar o histórico de transações e revisar o processo de integração

O processo de teste

O trabalho no Sandbox consiste em criar contas de teste de cliente para cada caso de uso da sua aplicação. Abaixo, um sumário do processo de teste:

  • Crie uma conta PayPal (de produção) e utilize essa conta para fazer login no site Developer: https://developer.paypal.com/
  • Crie uma série de contas de cliente e vendedor, para simular cada caso de uso da sua aplicação
  • Configure suas requisições à API para utilizar os detalhes de suas contas e execute as requisições nos endpoints do Sandbox.
  • Revise as respostas e faça os ajustes na sua aplicação, quando necessários.
  • Quando sua aplicação estiver completamente testada, cobrindo todos os casos de uso, e sem bugs, vá para produção apenas modificando as credenciais da API e os endpoints das requisições

Dica!Quando você cria uma nova conta PayPal, você precisa verificar o email dessa conta antes de utilizá-la. Verifique sua caixa de email e localize o email enviado pela PayPal. Caso não tenha recebido o email em alguns minutos, verifique se não foi bloqueado ou se não foi marcado como spam.

Dica!Quado você estiver criando uma nova conta no Developer, considere criar uma conta que não utilize sua conta de produção. Ao fazer isso, você poderá compartilhar a conta do Developer com outros desenvolvedores, sem que isso comprometa a segurança da sua conta de produção.

Criando contas de teste

Contas de teste no Sandbox, são contas PayPal virtuais, que apenas existem no ambiente Sandbox. Essas contas representam os clientes dos mock de transações que serão criadas enquanto você estiver na fase de testes da sua aplicação. Crie ao menos uma conta de teste para cada caso de uso, quando você estiver testando sua integração com as APIs.

O Sandbox suporta dois tipos diferentes de contas:

  • Pessoal – representa o cliente que está comprando na loja.
  • Vendedor – representa a loja, que está vendendo seus produtos.

Atenção!Para testar uma transação PayPal típica, você precisa de pelo menos uma conta de cliente e uma conta de vendedor. Quando você se registra no Sandbox, uma conta de vendedor é criada automaticamente para facilitar o processo. Entretanto, para testar a integração, você precisará criar pelo menos uma conta de cliente.

Dica!O artigo Utilizando o novo PayPal Sandbox ilustra passo a passo como criar uma conta de teste no Sandbox

Gerando as credenciais da API

Todas as requisições à API PayPal requer que você utilize credenciais para verificar e garantir que a requisição está sendo feita por uma conta PayPal. As requisições no Sandbox não são diferentes, mas requerem que sejam utilizadas credenciais de teste, que são definidas no Sandbox para suas contas de vendedor.

As credenciais da API podem ser verificadas no ambiente Developer, clicando sobre a conta de vendedor, profile e, então, indo até a aba API credentials:

developer014

Atenção!O ambiente Sandbox e o ambiente de Produção utilizam credenciais diferentes. Tenha a certeza de utilizar as credenciais corretas dentro do ambiente que estiver trabalhando.

Dica!O artigo Utilizando o novo PayPal Sandbox ilustra passo a passo como gerar as credenciais da API para uma conta de teste no Sandbox

Fazendo chamadas da API

Uma vez configuradas as contas de testes e geradas as credenciais da API, você está pronto para fazer suas requisições no ambiente de testes Sandbox.

Cada API PayPal possui um conjunto de campos específicos, que variam de API para API. Contudo, em todas as requisições, os campos USER, PWD e SIGNATURE são comuns e identificam a conta que está fazendo a requisição. Além desses campos, o campo METHOD e VERSION são utilizados para identificar a API e sua versão.

Abaixo, um exemplo de requisição à operação SetExpressCheckout, da API Express Checkout:

<br />USER=API_username&<br />PWD=API_password&<br />SIGNATURE=API_signature&<br />VERSION=106.0&<br />METHOD=SetExpressCheckout&<br />PAYMENTREQUEST_0_PAYMENTACTION=SALE&<br />PAYMENTREQUEST_0_AMT=22.00&<br />PAYMENTREQUEST_0_CURRENCYCODE=BRL&<br />PAYMENTREQUEST_0_ITEMAMT=22.00&<br />PAYMENTREQUEST_0_INVNUM=1234&<br />L_PAYMENTREQUEST_0_NAME0=Item+A&<br />L_PAYMENTREQUEST_0_DESC0=Produto+A+110V&<br />L_PAYMENTREQUEST_0_AMT0=11.00&<br />L_PAYMENTREQUEST_0_QTY0=1&<br />L_PAYMENTREQUEST_0_ITEMAMT=11.00&<br />L_PAYMENTREQUEST_0_NAME1=Item+B&<br />L_PAYMENTREQUEST_0_DESC1=Produto+B+220V&<br />L_PAYMENTREQUEST_0_AMT1=11.00&<br />L_PAYMENTREQUEST_0_QTY1=1&<br />RETURNURL=http://PayPalPartner.com.br/VendeFrete?return=1&<br />CANCELURL=http://PayPalPartner.com.br/CancelaFrete<br />

Dica!Você pode utilizar o API Explorer para fazer testes de requisição de uma API PayPal. O API Explorer permite que você visualize a requisição e resposta das APIs, que poderão ajudá-lo na integração ou depuração da integração. Acesso o API Explorer através da seguinte URL: API Explorer

Fazendo testes negativos

Por padrão, o ambiente Sandbox imita o ambiente de produção. Porém, durante os testes, será necessário testar o comportamento de nossas aplicações em caso de erro. Esse tipo de teste chama-se teste negativo e pode ser feito no Sandbox com uma configuração bem simples.

Ativando os testes negativos

O primeiro passo é ativar o recurso na conta de teste do vendedor, para isso, vamos até a lista de contas de teste do ambiente developer, localizamos a conta de teste de vendedor e a selecionamos:

developer012

Após a seleção da conta de teste de vendedor, dois links serão exibidos. Ao clicar no link Profile, uma janela com os detalhes da conta abrirá. A aba Settings deverá ser selecionada:

negative_testing

Agora, basta ligar a opção Negative Testing e começar os testes.

Simulando erros específicos

No ambiente developer existe uma lista de erros que podem ocorrer durante a integração e suas respectivas descrições. Se observarmos a lista, veremos que existe um código, uma descrição curta e uma descrição longa. Todos esses erros podem ocorrer em diversos momentos durante a integração e precisamos estar preparados para eles.

Para testar erros que podem ocorrer na operação SetExpressCheckout, podemos utilizar o campo MAXAMT e passar o código do erro que queremos testar.

A função abaixo pode ser utilizado nas requisições em integrações PHP. Ele recebe dois parâmetros, o primeiro com os campos que serão enviados na requisição, e o segundo com a identificação do ambiente. Essa função pode ser utilizada para qualquer operação do Express Checkout, bastando apenas especificar o campo METHOD e os campos específicos da operação.

<br /><?php<br />/**<br /> * Envia uma requisição NVP para uma API PayPal.<br /> *<br /> * @param array $requestNvp Define os campos da requisição.<br /> * @param boolean $sandbox Define se a requisição será feita no sandbox ou no<br /> *                         ambiente de produção.<br /> *<br /> * @return array Campos retornados pela operação da API. O array de retorno poderá<br /> *               pode ser vazio, caso a operação não seja bem sucedida. Nesse caso,<br /> *               os logs de erro deverão ser verificados.<br /> */<br />function sendNvpRequest(array $requestNvp, $sandbox = false)<br />{<br />    //Endpoint da API<br />    $apiEndpoint  = 'https://api-3t.' . ($sandbox? 'sandbox.': null);<br />    $apiEndpoint .= 'paypal.com/nvp';<br /><br />    //Executando a operação<br />    $curl = curl_init();<br /><br />    curl_setopt($curl, CURLOPT_URL, $apiEndpoint);<br />    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);<br />    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);<br />    curl_setopt($curl, CURLOPT_POST, true);<br />    curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($requestNvp));<br /><br />    $response = urldecode(curl_exec($curl));<br /><br />    curl_close($curl);<br /><br />    //Tratando a resposta<br />    $responseNvp = array();<br /><br />    if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) {<br />        foreach ($matches['name'] as $offset => $name) {<br />            $responseNvp[$name] = $matches['value'][$offset];<br />        }<br />    }<br /><br />    //Verificando se deu tudo certo e, caso algum erro tenha ocorrido,<br />    //gravamos um log para depuração.<br />    if (isset($responseNvp['ACK']) && $responseNvp['ACK'] != 'Success') {<br />        for ($i = 0; isset($responseNvp['L_ERRORCODE' . $i]); ++$i) {<br />            $message = sprintf("PayPal NVP %s[%d]: %s\n",<br />                               $responseNvp['L_SEVERITYCODE' . $i],<br />                               $responseNvp['L_ERRORCODE' . $i],<br />                               $responseNvp['L_LONGMESSAGE' . $i]);<br /><br />            error_log($message);<br />        }<br />    }<br /><br />    return $responseNvp;<br />}<br />

Utilizando a função sendNvpRequest, podemos simular um erro de código de câmbio inválido, cujo código de erro é 10755. Para isso, definimos o campo MAXAMT como 107.55, por exemplo:

<br /><?php<br />//Incluindo o arquivo que contém a função sendNvpRequest<br />require 'sendNvpRequest.php';<br /><br />//Vai usar o Sandbox, ou produção?<br />$sandbox = true;<br /><br />//Baseado no ambiente, sandbox ou produção, definimos as credenciais<br />//e URLs da API.<br />if ($sandbox) {<br />    //credenciais da API para o Sandbox<br />    $user = 'conta-business_api1.test.com';<br />    $pswd = '1365001380';<br />    $signature = 'AiPC9BjkCyDFQXbSkoZcgqH3hpacA-p.YLGfQjc0EobtODs.fMJNajCx';<br /><br />    //URL da PayPal para redirecionamento, não deve ser modificada<br />    $paypalURL = 'https://www.sandbox.paypal.com/cgi-bin/webscr';<br />} else {<br />    //credenciais da API para produção<br />    $user = 'usuario';<br />    $pswd = 'senha';<br />    $signature = 'assinatura';<br /><br />    //URL da PayPal para redirecionamento, não deve ser modificada<br />    $paypalURL = 'https://www.paypal.com/cgi-bin/webscr';<br />}<br /><br />//Campos da requisição da operação SetExpressCheckout, como ilustrado acima.<br />$requestNvp = array(<br />    'USER' => $user,<br />    'PWD' => $pswd,<br />    'SIGNATURE' => $signature,<br /><br />    'VERSION' => '108.0',<br />    'METHOD'=> 'SetExpressCheckout',<br /><br />    'PAYMENTREQUEST_0_PAYMENTACTION' => 'SALE',<br />    'PAYMENTREQUEST_0_AMT' => '22.00',<br />    'PAYMENTREQUEST_0_CURRENCYCODE' => 'BRL',<br />    'PAYMENTREQUEST_0_ITEMAMT' => '22.00',<br />    'PAYMENTREQUEST_0_INVNUM' => '1234',<br /><br />    //Simulando o erro 10755<br />    'MAXAMT' => '107.55',<br /><br />    'L_PAYMENTREQUEST_0_NAME0' => 'Item A',<br />    'L_PAYMENTREQUEST_0_DESC0' => 'Produto A – 110V',<br />    'L_PAYMENTREQUEST_0_AMT0' => '11.00',<br />    'L_PAYMENTREQUEST_0_QTY0' => '1',<br />    'L_PAYMENTREQUEST_0_ITEMAMT' => '11.00',<br />    'L_PAYMENTREQUEST_0_NAME1' => 'Item B',<br />    'L_PAYMENTREQUEST_0_DESC1' => 'Produto B – 220V',<br />    'L_PAYMENTREQUEST_0_AMT1' => '11.00',<br />    'L_PAYMENTREQUEST_0_QTY1' => '1',<br /><br />    'RETURNURL' => 'http://PayPalPartner.com.br/VendeFrete?return=1',<br />    'CANCELURL' => 'http://PayPalPartner.com.br/CancelaFrete',<br />    'BUTTONSOURCE' => 'BR_EC_EMPRESA'<br />);<br /><br />//Envia a requisição e obtém a resposta da PayPal<br />$responseNvp = sendNvpRequest($requestNvp, $sandbox);<br /><br />//Se a operação tiver sido bem sucedida, redirecionamos o cliente para o<br />//ambiente de pagamento.<br />if (isset($responseNvp['ACK']) && $responseNvp['ACK'] == 'Success') {<br />    $query = array(<br />        'cmd'    => '_express-checkout',<br />        'token'  => $responseNvp['TOKEN']<br />    );<br /><br />    $redirectURL = sprintf('%s?%s', $paypalURL, http_build_query($query));<br /><br />    //header('Location: ' . $redirectURL);<br />} else {<br />    printf("Erro[%d]: %s\n", $responseNvp['L_ERRORCODE0'], $responseNvp['L_LONGMESSAGE0']);<br />}<br />

O código acima irá exibir a mensagem:

Erro[10755]: Currency is not supported

. A simulação de erros pode ocorrer em qualquer operação PayPal, para isso, basta enviar o campo especial da operação definido com o código do erro. Abaixo, a lista das operações e o campo que deverá ser enviado:

Operação Campo
SetExpressCheckout MAXAMT
GetExpressCheckoutDetails TOKEN
DoExpressCheckoutPayment AMT
DoAuthorization AMT
DoCapture AMT
DoReauthorization AMT
MassPay EMAILSUBJECT
RefundTransaction AMT
TransactionSearch INVNUM
UpdateAuthorization TRANSACTIONID

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 sumário do processo de migração para produção:

  • Crie uma conta no ambiente de produção: https://www.paypal.com/.
  • Gere as credenciais da API para o ambiente de produção. Veja o seguinte passo a passo: Gerar as credenciais da API.
  • Atualize as credenciais da API no seu código.
  • Atualize os endpoints da API no seu código. Abaixo, os endpoints de produção:
    • Endpoint da APIhttps://api-3t.paypal.com/nvp.
    • Endpoint do redirecionamentohttps://www.paypal.com/cgi-bin/webscr?cmd=_expresscheckout&useraction=commit&token={TOKEN}.