Notificaciones IPN
Introducción
IPN (Instant Payment Notification) es una notificación que se envía de un servidor a otro mediante una llamada HTTP POST
en relación a tus transacciones.
Para recibir las notificaciones de los eventos en tu plataforma, puedes configurar previamente una notification_url a la cual Mercado Pago tenga acceso.
Eventos
Notificamos eventos referidos a tus órdenes (merchant_orders
), pagos recibidos (payment
) o contracargos recibidos (chargebacks
).
La merchant_orders
es una entidad que agrupa tanto pagos como envíos. Tendrás que consultar los datos de las órdenes que te sean notificadas.
Siempre que suceda un evento relacionado a alguno de los recursos mencionados, te enviaremos una notificación usando HTTP POST
a la notification_url
que especificaste.
Si la aplicación no está disponible o demora en responder más de 22 segundos, Mercado Pago reintentará la notificación mediante el siguiente esquema:
- Reintento a los 5 minutos.
- Reintento a los 45 minutos.
- Reintento a las 6 horas.
- Reintento a los 2 días.
- Reintento a los 4 días.
Mercado Pago informará a esta notification_url
tanto en la creación como actualización de los estados de pagos u ordenes con dos parámetros:
Campo | Descripción |
---|---|
topic | Identifica de qué se trata. Puede ser payment , chargebacks o merchant_order |
id | Es un identificador único del recurso notificado. |
Ejemplo: Si configuraste la notification_url: https://www.yoursite.com/notifications
, recibirás notificaciones de pago de esta manera: https://www.yoursite.com/notifications?topic=payment&id=123456789
¿Qué debo hacer al recibir una notificación?
Cuando recibas una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recibiste correctamente. Para esto, debes devolver un HTTP STATUS 200 (OK)
ó 201 (CREATED)
.
Recuerda que esta comunicación es exclusivamente entre los servidores de Mercado Pago y tu servidor, por lo cual no habrá un usuario físico viendo ningún tipo de resultado.
Luego de esto, puedes obtener la información completa del recurso notificado accediendo a la API correspondiente en https://api.mercadopago.com/
:
Tipo | URL | Documentación |
---|---|---|
payment | /v1/payments/[ID] | ver documentación |
chargebacks | /v1/chargebacks/[ID] | - |
merchant_orders | /merchant_orders/[ID] | ver documentación |
Con esta información puedes realizar las actualizaciones necesarias en tu plataforma, por ejemplo registrar un pago acreditado o una orden cerrada.
Notificaciones de merchant_orders
Si estas integrando pagos presenciales, te recomendamos utilizar notificaciones IPN de topic merchant_order
. Para ello, ten en cuenta las siguientes reglas:
- El campo
status
de lamerchant_order
permanecerá en opened cuando aún no tenga pagos asociados, o los tenga y estén rechazados o aprobados por un monto menor al total de la orden. - El campo
status
de lamerchant_order
será closed cuando la suma de los pagos aprobados sea igual o mayor al total de la orden.
Dentro de la orden, en el objeto payments, encontrarás todos los pagos de la misma. Es importante obtener el id de los pagos con status
= approved para poder realizar devoluciones.
Implementa el receptor de notificaciones tomando como ejemplo el siguiente código:
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
, revisa la sección de CredencialesBúsqueda de la orden
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.
curl
curl -X GET \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadopago.com/merchant_orders?external_reference=$EXTERNAL_REFERENCE
Más información en la Referencia de API.
Se puede implementar la búsqueda por external_reference
de dos formas:
Formas | Descripción |
---|---|
Manual | El punto de venta debe incluir un botón para realizar la búsqueda. |
Automática | Pasado un tiempo prudencial sin haber recibido alguna notificación, se comienza una búsqueda de la orden cada un intervalo de, por ejemplo, 5 segundos. |
Por cada escaneo del QR se genera una merchant_order
distinta. Debe considerarse que si el cliente escanea más de una vez, una orden quedará en open por tiempo indefinido. Debe tomarse la merchant_order
con el status
= closed para cerrar la transacción.
Si se realiza la búsqueda una vez escaneado el QR, se obtienen todos los datos referidos a la orden:
json
{
"id": 1126664483,
"status": "closed",
"payments": [
{
"id": 4996721469,
"transaction_amount": 4,
"status": "rejected",
[...],
},
{
"id": 4996721476,
"transaction_amount": 4,
"status": "approved",
[...], },
En caso contrario, la respuesta que se recibe si todavía no se escaneó el QR al cual se publicó la orden será:
json
{
"elements": null,
"next_offset": 0,
"total": 0
}
Recibir un solo tipo de notificación
Si quieres recibir solamente las notificaciones de IPN, y no de Webhooks, puedes agregar en la notification_url el parámetro source_news=ipn
. Como por ejemplo:
https://www.yourserver.com/notifications?source_news=ipn