Tabela de conteúdo

1. Introdução
2. Operação TransactionSearch
   1. Critérios de busca
3. Implementação
4. Veja também

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.
EMAIL	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: All – Vai retornar todas as transações, seria o mesmo que não enviar esse campo. Sent – Somente transações de pagamentos enviados serão retornadas. Received – Somente transações de pagamentos recebidos serão retornadas. Refund – Somente transações envolvendo estornos.
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: Pending – Vai retornar apenas as transações pendente de revisão. Processing – Vai retornar apenas as transações que estão em processamento. Success – Vai retornar apenas as transações bem sucedidas, ou seja, aquelas que o pagamento foi concluído e o dinheiro transferido para o vendedor.

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.

Veja também

• Utilizando o novo PayPal Sandbox
• Guia rápido para receber pagamentos com conta bancária