Introdução

Pagamentos em lote permite que você envie dinheiro para um ou mais recebedores. De fato, é possível enviar pagamentos para até 250 recebedores, com apenas uma requisição.

Neste artigo veremos como enviar esse tipo de pagamento em lote via API, abordando desde a criação da requisição, manipulação da resposta e recebimento das notificações de pagamento

Requisições à API

A API MassPay permite que você envie pagamentos para até, no máximo, 250 recebedores, com uma única requisição à API. O valor que cada recebedor receberá é especificado individualmente, porém, todos os pagamentos precisam, necessariamente, utilizar a mesma moeda. É possível enviar pagamentos especificando o email ou ID da conta do cliente. Quando a PayPal receber a requisição, vai retornar um conjunto de campos indicando sucesso ou falha. Caso a operação seja bem sucedida e você estiver com as notificações instantâneas de pagamento (IPN) ativadas, então a PayPal vai enviar uma notificação com detalhes sobre cada pagamento.

Antes de fazer uma requisição à API, é importante notar que os Pagamentos em Lote só podem ser financiados com seu saldo no PayPal. Portanto, use os pagamentos que receber em sua conta do PayPal para fazer Pagamentos em Lote. Outro ponto é que, quando você tem uma conta brasileira do PayPal, todos os pagamentos enviados a brasileiros devem ser em reais. Além disso, você só pode fazer pagamentos internacionais em lote se tiver saldo em moeda estrangeira.

Campos da Requisição

Além dos campos requeridos por qualquer requisição NVP, uma requisição MassPay possui alguns campos específicos. A tabela abaixo descreve todos os campos de uma requisição MassPay:

Nome do campo	Descrição
USER PWD SIGNATURE	São as credenciais da API. Se você ainda não tem as credenciais da API, veja esse link.
VERSION	Versão da API. A última versão é a 99
METHOD	Nome da operação. Nesse caso, será MassPay
EMAILSUBJECT	Esse campo definirá o assunto do email que o cliente receberá sobre o pagaento.
CURRENCYCODE	Moeda que será utilizada nos pagamentos. Lembrando que quando você tem uma conta brasileira do PayPal, todos os pagamentos enviados a brasileiros devem ser em reais. Além disso, você só pode fazer pagamentos internacionais em lote se tiver saldo em moeda estrangeira.
RECEIVERTYPE	Tipo de envio. Os seguintes tipos são possíveis: EmailAddress UserID PhoneNumber
L_EMAILn	Define o email do recebedor. O n deve ser substituído pelo índice do envio, começando em 0 e indo até, no máximo, 249. Por exemplo L_EMAIL0=primeiro-recebedor@cliente.com.br& L_EMAIL1=segundo-recebedor@cliente.com.br& ... L_EMAIL249=ultimo-recebedor@cliente.com.br
L_AMTn	Define o valor do pagamento que o cliente receberá. O n deve ser substituído pelo índice do envio, começando em 0 e indo até, no máximo, 249. Por exemplo L_AMT0=100.00& L_AMT1=200.00& ... L_AMT249=300.00

Requisição de Exemplo

[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_URL, ‘https://api-3t.sandbox.paypal.com/nvp’);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array(
‘USER’ => ‘USUARIO-DA-API’,
‘PWD’ => ‘SENHA DA API’,
‘SIGNATURE’ => ‘ASSINATURA DA API’,

‘METHOD’ => ‘MassPay’,
‘VERSION’ => ’99’,

‘CURRENCYCODE’ => ‘BRL’,
‘RECEIVERTYPE’ => ‘EmailAddress’,
‘EMAILSUBJECT’ => ‘Assunto do email que o cliente receberá’,

‘L_EMAIL0’ => ‘fulano@cliente.com’,
‘L_AMT0’ => 100.00,

‘L_EMAIL1’ => ‘beltrano@cliente.com’,
‘L_AMT1’ => 200.00,

‘L_EMAIL2’ => ‘cicrano@cliente.com’,
‘L_AMT2’ => 300.00
)));

$response = curl_exec($curl);

curl_close($curl);
[/php]

Resposta da Requisição

A resposta da operação MassPay é igual a qualquer requisição NVP. Não existe um campo específico somente para a MassPay.

[code]
Array
(
[TOKEN] => EC-0A9774676H705661Y
[TIMESTAMP] => 2012-10-08T13:11:19Z
[CORRELATIONID] => aaea15b01caab
[ACK] => Success
[VERSION] => 91
[BUILD] => 3893058
)
[/code]

Para verificar o sucesso ou falha da operação, tudo o que precisamos fazer é verificar o campo ACK. Success indica que o envio foi bem sucedido, Failure indica que houve uma falha no envio dos pagamentos, por exemplo:

[php]
<?php
//…
$response = urldecode(curl_exec($curl));
$responseNvp = array();

curl_close($curl);

if (preg_match_all(‘/(?<name>[^\=]+)\=(?<value>[^&]+)&?/’, $response, $matches)) {
foreach ($matches[‘name’] as $offset => $name) {
$responseNvp[$name] = $matches[‘value’][$offset];
}
}

if (isset($responseNvp[‘ACK’]) && $responseNvp[‘ACK’] == ‘Success’) {
//sucesso
} else {
//falha
}
[/php]

Recebendo notificações IPN

Se você tiver habilitado o IPN para a sua conta, então serão enviadas duas notificações para a URL especificada em seu conta PayPal, para cada pagamento feito. Essas notificações são enviadas, primeiro quando os fundos para o pagamento foram retirados de da conta de quem está enviando, depois quando o pagamento estiver concluído.

Se todos os destinatários puderem receber o pagamento, o PayPal envia essas notificações apenas alguns segundos após o processamento. Se um ou mais destinatários não pode receber o pagamento, a notificação Completed é enviada quando todos os receptores forem capazes de receber o pagamento. Se após 30 dias ainda houver algum recebedor que não foi capaz de receber o pagamento, a notificação Completed é enviada com informações sobre quais pagamentos falharam e o valor que não foi pago é devolvido para a conta que enviou o pagamento.

Note: Um recebedor pode receber o pagamento via Mass Pay se tiver uma conta PayPal com um endereço de e-mail confirmado.

Pagamentos processados

A notificação de pagamentos processados é enviada quando o valor do pagamento é retirado da conta de quem está enviando o pagamento. Para cada transação, um ID único é gerado e retornado na variável masspay_txn_id, assim como a variável unique_id. A variável unique_id é um identificador único da chamada à API MassPay, para que seu sistema possa acompanhar as duas notificações que serão enviadas.

Além dos identificadores, a PayPal também enviará o status do pagamento, que poderá ser Completed, Failed, Reversed ou Unclaimed. Abaixo, um exemplo de notificação enviada pela PayPal:

[code]
payer_id=HZU8ZEBYHLEZQ&
payment_date=18%3A01%3A16+Apr+18%2C+2013+UTC&
payment_gross_1=25.99&
payment_gross_2=9.99&
payment_status=Processed&
receiver_email_1=fulano@exemplo.com&
receiver_email_2=beltrano@exemplo.com&
charset=windows-1252&
mc_currency_1=BRL&
masspay_txn_id_1=5W531651W5136225N&
mc_currency_2=BRL&
masspay_txn_id_2=8P09425963946233T&
first_name=Fulano&
unique_id_1=12345&
notify_version=2.1&
unique_id_2=45678&
payer_status=verified&
verify_sign=AB5URHwIzIbcANTQUdSveiWRw8-WACTmrKK-dops2Tb6KKAQnpUJyF.l
&payer_email=empresa@brasileira.com&
payer_business_name=Uma+Empresa+de+Teste&
last_name=Tal&
status_1=Completed&
status_2=Unclaimed&
txn_type=masspay&
mc_gross_1=25.99&
mc_gross_2=9.99&
payment_fee_1=0.52&
residence_country=BR&
payment_fee_2=0.20&
test_ipn=1&
mc_fee_1=0.52&
mc_fee_2=0.20
[/code]

Pagamentos concluídos

A notificação de pagamentos concluídos é enviada quando todos os recebedores foram capazes de receber o pagamento, ou quando 30 dias se passaram. Abaixo uma notificação IPN para pagamentos concluídos.

[code]
payer_id=HZU8ZEBYHLEZQ&
payment_date=18%3A05%3A00+Apr+18%2C+2013+UTC&
payment_gross_1=25.99&
payment_gross_2=9.99&
payment_status=Completed&
receiver_email_1=fulano@exemplo.com&
receiver_email_2=beltrano@exemplo.com&
mc_currency_1=BRL&
masspay_txn_id_1=5W531651W5136225N&
mc_currency_2=BRL&
masspay_txn_id_2=8P09425963946233T&
first_name=Fulano&
unique_id_1=12345&
notify_version=2.1&
unique_id_2=45678&
payer_status=verified&
verify_sign=AgHNi5eT0bHgt8xiwqeAG7bDTOsvAkW2ba1G3x3K7ayAOd.bmkafCd-f&
payer_email=empresa@brasileira.com&
payer_business_name=Uma+Empresa+de+Teste&
last_name=Tal&
status_1=Completed&
status_2=Completed&
txn_type=masspay&
mc_gross_1=25.99&
mc_gross_2=9.99&
payment_fee_1=0.52&
residence_country=BR&
payment_fee_2=0.20&
test_ipn=1&
mc_fee_1=0.52&
mc_fee_2=0.20
[/code]