Tabela de conteúdo
Introdução
A operação TransactionSearch da API do PayPal permite que as aplicações enviem alguns campos que especificam os critérios da busca e retorna uma lista de transações que atendam à esses critérios.
Do ponto de vista do operador do sistema, essa integração se parece com o seguinte:
Como podemos ver, o operador pode pesquisar por transações, listá-las, ver detalhes e, se for o caso, fazer a captura do valor ou até o estorno. Ao fazer a integração com o PayPal, a listagem depende da pesquisa que pode ser feita por vários critérios.
Critérios de busca
Vou listar abaixo apenas alguns desses campos, para a listagem completa a página da documentação deve ser consultada: Documentação TransactionSearch.
Campo | Descrição |
---|---|
STARTDATE | Esse é o único campo obrigatório e especifica a data inicial. Qualquer transação cuja data for maior ou igual a especificada em STARTDATE será retornada pelo PayPal. |
ENDDATE | Ao contrário da STARTDATE, esse campo é opcional e especifica a data final. Qualquer transação que estiver entre a data inicial e a data final (inclusive) serão retornadas pela operação TransactionSearch. |
O campo email é utilizado para pesquisar transações de um comprador específico, se informado, apenas as transações daquele comprador serão retornadas. | |
RECEIVER | Assim como o campo EMAIL, esse campo recebe um email, porém, o email do vendedor. Esse campo não é muito útil em lojas que operam com apenas 1 vendedor, mas em market places, que operam com vários vendedores, esse campo pode ser extremamente útil. |
TRANSACTIONID | Sempre que uma transação é criada no PayPal, um identificador de transação é retornado para a aplicação. Para pesquisar uma transação específica, podemos informar o id dessa transação nesse campo. |
TRANSACTIONCLASS | Existem diversas classes de transações e podemos pesquisar por transações que estejam em uma classe específica:
|
AMT | Esse campo permite uma pesquisa pelo valor da transação. |
CURRENCYCODE | Esse campo permite pesquisar as transações que foram feitas em uma determinada moeda (USD, BRL, etc.). |
STATUS | Permite uma pesquisa pelo status da transação:
|
Além dos campos relacionados com a transação, é possível especificar alguns dados com comprador:
FIRSTNAME, MIDDLENAME e LASTNAME – Esses campos podem ser utilizados para pesquisar pelo nome do comprador, seja o primeiro nome ou último nome.
Implementação
A operação TransactionSearch da API do PayPal oferece duas inferfaces distintas: NVP e SOAP. Neste artigo vamos tratar apenas da interface NVP, onde uma lista de pares nome=valor são enviados para o PayPal.
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 de qualquer API NVP, bastando apenas especificar o campo METHOD
e os campos específicos da operação.
<?php /** * Envia uma requisição NVP para uma API PayPal. * * @param array $requestNvp Define os campos da requisição. * @param boolean $sandbox Define se a requisição será feita no sandbox ou no * ambiente de produção. * * @return array Campos retornados pela operação da API. O array de retorno poderá * pode ser vazio, caso a operação não seja bem sucedida. Nesse caso, * os logs de erro deverão ser verificados. */ function sendNvpRequest(array $requestNvp, $sandbox = false) { //Endpoint da API $apiEndpoint = 'https://api-3t.' . ($sandbox? 'sandbox.': null); $apiEndpoint .= 'paypal.com/nvp'; //Executando a operação $curl = curl_init(); curl_setopt($curl, CURLOPT_URL, $apiEndpoint); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($requestNvp)); $response = urldecode(curl_exec($curl)); curl_close($curl); //Tratando a resposta $responseNvp = array(); if (preg_match_all('/(?<name>[^\=]+)\=(?<value>[^&]+)&?/', $response, $matches)) { foreach ($matches['name'] as $offset => $name) { $responseNvp[$name] = $matches['value'][$offset]; } } //Verificando se deu tudo certo e, caso algum erro tenha ocorrido, //gravamos um log para depuração. if (isset($responseNvp['ACK']) && $responseNvp['ACK'] != 'Success') { for ($i = 0; isset($responseNvp['L_ERRORCODE' . $i]); ++$i) { $message = sprintf("PayPal NVP %s[%d]: %s\n", $responseNvp['L_SEVERITYCODE' . $i], $responseNvp['L_ERRORCODE' . $i], $responseNvp['L_LONGMESSAGE' . $i]); error_log($message); } } return $responseNvp; }
Para listar todas as transações ocorridas desde o início de Fevereiro de 2014, a requisição se parecerá com o seguinte:
USER=API_username PWD=API_password SIGNATURE=API_signature VERSION=108.0 METHOD=TransactionSearch STARTDATE=2014-02-01T00:00:00Z
Utilizando a função de exemplo, a requisição acima poderá ser feita como abaixo:
<?php //Incluindo o arquivo que contém a função sendNvpRequest require 'sendNvpRequest.php'; //Vai usar o Sandbox, ou produção? $sandbox = true; //Baseado no ambiente, sandbox ou produção, definimos as credenciais //e URLs da API. if ($sandbox) { //credenciais da API para o Sandbox $user = 'conta-business_api1.test.com'; $pswd = '1365001380'; $signature = 'AiPC9BjkCyDFQXbSkoZcgqH3hpacA-p.YLGfQjc0EobtODs.fMJNajCx'; } else { //credenciais da API para produção $user = 'usuario'; $pswd = 'senha'; $signature = 'assinatura'; } //Campos da requisição da operação TransactionSearch, como ilustrado acima. $requestNvp = array( 'USER' => $user, 'PWD' => $pswd, 'SIGNATURE' => $signature, 'VERSION' => '108.0', 'METHOD'=> 'TransactionSearch', 'STARTDATE' => '2014-02-03T00:00:00Z' ); //Envia a requisição e obtém a resposta da PayPal $responseNvp = sendNvpRequest($requestNvp, $sandbox); //Se a operação tiver sido bem sucedida, podemos listar as transações encontradas if (isset($responseNvp['ACK']) && $responseNvp['ACK'] == 'Success') { print_r($responseNvp); } else { //Opz, alguma coisa deu errada. //Verifique os logs de erro para depuração. }
Retorno da API
Quando a operação TransactionSearch for chamada, uma lista de transações será retornada com os seguintes campos:
Atenção!
As mensagens enviadas pela PayPal, utilizam o conjunto de caracteres Win-2512. Se sua aplicação utilizar outro conjunto de caracteres, como UTF-8, veja o seguinte passo a passo para atualização: Configurando o conjunto de caracteres para troca de mensagens.
Campo | Descrição |
---|---|
L_TIMESTAMP | Informa o timestamp do momento que a transação foi criada |
L_TIMEZONE | Informa o timezone da transação |
L_TYPE | Informa o tipo da transação |
L_EMAIL | Informa o email do recebedor ou do pagador. Se o valor do pagamento for positivo, então esse email é do recebedor, do contrário é do pagador |
L_NAME | Informa o nome de exibição do comprador |
L_TRANSACTIONID | Informa o identificador da transação |
L_STATUS | Informa o status da transação |
L_AMT | Informa o valor bruto da transação, incluindo taxas e despesas de entrega. |
L_FEEAMT | Informa o valor de taxa da transação. |
L_NETAMT | Informa o valor líquido da transação. |