Notificações IPN
O IPN (Instant Payment Notification) é uma notificação enviada de um servidor a outro mediante uma chamada HTTP POST
para informar sobre suas transações.
Para receber notificações de eventos na sua plataforma, você pode configurar previamente uma notification_url à qual Mercado Pago tiver acesso.
Eventos
Notificamos eventos relacionados aos seus pedidos (merchant_orders
), estornos recebidos (chargebacks
) ou pagamentos recebidos (payment
).
A merchant_order
é uma entidade que pode conter tanto pagamentos como envios. Você terá que consultar os dados dos pedidos notificados.
Sempre que ocorrer um evento relacionado a algum dos recursos mencionados, enviaremos uma notificação utilizando HTTP POST
para a URL especificada.
Se a aplicação não estiver disponível ou demorar para responder, o Mercado Pago irá fazer tentativas de notificação nos seguintes intervalos:
- Tentativa após 5 minutos.
- Tentativa após 45 minutos.
- Tentativa após 6 horas.
- Tentativa após 2 dias.
- Tentativa após 4 dias.
O Mercado Pago informará essa URL quando um recurso for criado ou quando houver atualização do status dos pagamentos ou pedidos, com dois parâmetros:
Campo | Descrição |
---|---|
topic | Identifica do que se trata o recurso. Pode ser payment , chargebacks ou merchant_order |
id | É um identificador único do recurso notificado. |
Exemplo: Se configurar a URL: https://www.yoursite.com/notifications
, você receberá as notificações de pagamento desta maneira: https://www.yoursite.com/notifications?topic=payment&id=123456789
.
O que devo fazer ao receber uma notificação?
Quando receber uma notificação na sua plataforma, o Mercado Pago espera uma resposta para validar que a recebeu corretamente. Para isso, você deve retornar um HTTP STATUS 200 (OK)
ou 201 (CREATED)
.
Lembre-se que esta comunicação é feita exclusivamente entre os servidores do Mercado Pago e o seu servidor, de modo que não haverá um usuário físico vendo nenhum tipo de resultado.
Depois disso, você poderá obter a informação completa do recurso notificado acessando a API correspondente em https://api.mercadopago.com/
:
Tipo | URL | Documentação |
---|---|---|
payment | /v1/payments/[ID] | ver documentação |
chargebacks | /v1/chargebacks/[ID] | - |
merchant_orders | /merchant_orders/[ID] | ver documentação |
Com essas informações, você poderá realizar as atualizações necessárias na sua plataforma, por exemplo: atualizar um pagamento aprovado o un pedido fechado.
Notificações para pagamentos presenciais
Se você estiver integrando pagamentos presenciais, recomendamos utilizar notificações IPN de topic merchant_order
. Para isso, lembre das seguintes regras:
- O campo
status
damerchant_order
permanecerá em opened quando ainda não tiver pagamentos associados, ou tiver pagamentos recusados ou aprovados por um valor menor ao total da ordem. - O campo
status
damerchant_order
será closed quando a soma dos pagamentos aprovados for igual ou superior ao total da ordem.
Dentro da ordem, no objeto payments, você vai encontrar todos os pagamentos dela. É importante obter a ID dos pagamentos com status = approved para poder realizar restituições.
Implemente o receptor de notificações usando o seguinte código como exemplo:
php
<?php
MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
$merchant_order = null;
switch($_GET["topic"]) {
case "payment":
$payment = MercadoPago\Payment::find_by_id($_GET["id"]);
// Get the payment and the corresponding merchant_order reported by the IPN.
$merchant_order = MercadoPago\MerchantOrder::find_by_id($payment->order->id);
break;
case "merchant_order":
$merchant_order = MercadoPago\MerchantOrder::find_by_id($_GET["id"]);
break;
}
$paid_amount = 0;
foreach ($merchant_order->payments as $payment) {
if ($payment['status'] == 'approved'){
$paid_amount += $payment['transaction_amount'];
}
}
// If the payment's transaction amount is equal (or bigger) than the merchant_order's amount you can release your items
if($paid_amount >= $merchant_order->total_amount){
if (count($merchant_order->shipments)>0) { // The merchant_order has shipments
if($merchant_order->shipments[0]->status == "ready_to_ship") {
print_r("Totally paid. Print the label and release your item.");
}
} else { // The merchant_order don't has any shipments
print_r("Totally paid. Release your item.");
}
} else {
print_r("Not paid yet. Do not release your item.");
}
?>
ACCESS_TOKEN
, verifique a seção de CredenciaisPesquisa da ordem
Si estas integrando pagos presenciales, se debe implementar como método de contingencia, la búsqueda de la orden utilizando el external_reference
de la misma como criterio de búsqueda.
Se você estiver integrando pagamentos presenciais, é necessário aplicar como método de contingência a pesquisa da ordem utilizando o seu external_reference
como critério de pesquisa.
curl
curl -X GET \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadopago.com/merchant_orders?external_reference=$EXTERNAL_REFERENCE
Mais informações na Referência de API.
A pesquisa pode ser realizada por external_reference
de duas formas:
Formas | Descrição |
---|---|
Manual | O ponto de venda deve incluir um botão para realizar a pesquisa. |
Automática | Após um tempo razoável sem ter recebido qualquer notificação, é iniciada uma pesquisa da ordem a cada um intervalo de, por exemplo, 5 segundos. |
Por cada escaneamento do QR é gerada uma merchant_order
diferente. Lembre que caso o cliente faça mais de um escaneamento, uma ordem ficará em open por tempo indefinido. Para encerrar a transação, a merchant_order
deve ter status
= closed.
Caso a pesquisa seja realizada após o escaneamento do QR, vão se obter todos os dados referidos à ordem:
json
{
"id": 1126664483,
"status": "closed",
"payments": [
{
"id": 4996721469,
"transaction_amount": 4,
"status": "rejected",
[...],
},
{
"id": 4996721476,
"transaction_amount": 4,
"status": "approved",
[...], },
Caso contrário, se o QR no qual a ordem foi publicada ainda não foi escaneado, a resposta será:
json
{
"elements": null,
"next_offset": 0,
"total": 0
}
Receber apenas um tipo de notificação
Se deseja receber notificações apenas de IPN, e não de Webhooks, você pode adicionar na notification_url o parâmetro source_news=ipn
. Como por exemplo:
https://www.yourserver.com/notifications?source_news=ipn