IPN
IPN (Instant Payment Notification) es un mecanismo que permite que tu aplicación reciba notificaciones de Mercado Pago, informando el estado de un determinado pago, contracargo y merchant order, a través de una llamada HTTP POST para informar sobre sus transacciones.
Las notificaciones IPN pueden ser configuradas de dos maneras:
Tipo de configuraciĂłn | DescripciĂłn |
Configuración a través de Tus integraciones | Podrå ser configurada solo una URL de notificación por cuenta (dependiendo de la aplicación, mås de una de ellas podrå usar la URL). |
ConfiguraciĂłn durante la creaciĂłn de un pago, preferencia u orden | Puede ser realizada a partir del campo notification_url . La URL podrĂĄ ser diferente para cada objeto. |
En esta documentación explicaremos cómo realizar la configuración necesaria para recibir notificaciones IPN a través de Tus integraciones o al momento de crear pagos, y te mostraremos las acciones necesarias para que Mercado Pago valide que los mensajes fueron recibidos correctamente.
Configuración a través de Tus integraciones
Puedes configurar notificaciones IPN directamente desde Tus integraciones de manera eficiente y segura.
Indicar URLs y configurar eventos
Para configurar notificaciones IPN mediante Tus integraciones, es necesario indicar las URLs a las que las mismas serĂĄn enviadas y especificar los eventos para los cuales deseas recibirlas.
Para configurar URLs y eventos, sigue el paso a paso a continuaciĂłn:
- Ingresa a Tus Integraciones y selecciona una de las aplicaciones para activar las notificaciones para toda tu cuenta. En caso de que aĂșn no hayas creado una aplicaciĂłn, accede a la documentaciĂłn sobre el Panel del Desarrollador y sigue las instrucciones para poder hacerlo.
- En el menĂș de la izquierda, selecciona IPN, y configura la URLs de producciĂłn que serĂĄ utilizada para recibir las notificaciones. TambiĂ©n podrĂĄs probar si la URL indicada estĂĄ recibiendo notificaciones correctamente, verificando la solicitud, la respuesta dada por el servidor y la descripciĂłn del evento.
- Selecciona los eventos para los cuales deseas recibir las notificaciones, que serĂĄn enviadas en formato
JSON
a través de unHTTP POST
a la URL especificada anteriormente. Un evento puede ser cualquier actualización sobre el tópico reportado, incluyendo cambios de status o atributos. Consulta la tabla a continuación para ver qué eventos pueden ser configurados teniendo en cuenta la solución de Mercado Pago integrada y las particularidades de negocio.
Eventos | Nombre en Tus integraciones | TĂłpico | Productos asociados |
CreaciĂłn y actualizaciĂłn de pagos | Pagos | payment | Checkout Transparente Checkout Pro Checkout Bricks Suscripciones Mercado Pago Point Wallet Connect |
FinalizaciĂłn, cancelaciĂłn o errores al procesar intenciones de pago de dispositivos Mercado Pago Point. | Integraciones Point | point_integration_ipn | Mercado Pago Point |
Alertas de fraude luego del procesamiento de un pedido | Alertas de fraude | delivery_cancellation | Checkout Transparente Checkout PRO |
CreaciĂłn, actualizaciĂłn o cierre de Ăłrdenes comerciales | Ărdenes comerciales | merchant_order | Checkout Pro CĂłdigo QR |
Apertura de contracargos, cambios de status y modificaciones referentes a las liberaciones de dinero. | Contracargos | chargebacks | Checkout Pro Checkout Transparente Checkout Bricks |
ConfiguraciĂłn durante la creaciĂłn de un pago
Durante el proceso de creaciĂłn de pagos, preferencias u Ăłrdenes presenciales, es posible configurar la URL de notificaciĂłn de forma mĂĄs especĂfica para cada pago, utilizando el campo notification_url
e implementando un receptor de notificaciones.
A continuaciĂłn, explicamos cĂłmo configurar notificaciones IPN al crear un pago usando los SDK.
- En el campo
notification_url
, indica la URL desde la que se recibirĂĄn las notificaciones, como se muestra a continuaciĂłn. Para recibir notificaciones exclusivamente vĂa IPN y no vĂa Webhooks, es posible agregar el parĂĄmetrosource_news=ipn
a lanotification_url
. Por ejemplo:https://www.yourserver.com/notifications?source_news=ipn
.
<?php
require_once 'vendor/autoload.php';
MercadoPago\SDK::setAccessToken("YOUR_ACCESS_TOKEN");
$payment = new MercadoPago\Payment();
$payment->transaction_amount = (float)$_POST['transactionAmount'];
$payment->token = $_POST['token'];
$payment->description = $_POST['description'];
$payment->installments = (int)$_POST['installments'];
$payment->payment_method_id = $_POST['paymentMethodId'];
$payment->issuer_id = (int)$_POST['issuer'];
$payment->notification_url = `http://requestbin.fullcontact.com/1ogudgk1`;
...
$response = array(
'status' => $payment->status,
'status_detail' => $payment->status_detail,
'id' => $payment->id
);
echo json_encode($response);
?>
var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken("YOUR_ACCESS_TOKEN");
var payment_data = {
transaction_amount: Number(req.body.transactionAmount),
token: req.body.token,
description: req.body.description,
installments: Number(req.body.installments),
payment_method_id: req.body.paymentMethodId,
issuer_id: req.body.issuer,
notification_url: "http://requestbin.fullcontact.com/1ogudgk1",
payer: {
email: req.body.email,
identification: {
type: req.body.docType,
number: req.body.docNumber
}
}
};
mercadopago.payment.save(payment_data)
.then(function(response) {
res.status(response.status).json({
status: response.body.status,
status_detail: response.body.status_detail,
id: response.body.id
â });
})
.catch(function(error) {
res.status(response.status).send(error);
});
MercadoPago.SDK.setAccessToken("YOUR_ACCESS_TOKEN");
Payment payment = new Payment();
payment.setTransactionAmount(Float.valueOf(request.getParameter("transactionAmount")))
.setToken(request.getParameter("token"))
.setDescription(request.getParameter("description"))
.setInstallments(Integer.valueOf(request.getParameter("installments")))
.setPaymentMethodId(request.getParameter("paymentMethodId"))
.setNotificationUrl("http://requestbin.fullcontact.com/1ogudgk1");
Identification identification = new Identification();
identification.setType(request.getParameter("docType"))
.setNumber(request.getParameter("docNumber"));
Payer payer = new Payer();
payer.setEmail(request.getParameter("email"))
.setIdentification(identification);
payment.setPayer(payer);
payment.save();
System.out.println(payment.getStatus());
require 'mercadopago'
sdk = Mercadopago::SDK.new('YOUR_ACCESS_TOKEN')
payment_data = {
transaction_amount: params[:transactionAmount].to_f,
token: params[:token],
description: params[:description],
installments: params[:installments].to_i,
payment_method_id: params[:paymentMethodId],
notification_url: "http://requestbin.fullcontact.com/1ogudgk1",
payer: {
email: params[:email],
identification: {
type: params[:docType],
number: params[:docNumber]
}
}
}
payment_response = sdk.payment.create(payment_data)
payment = payment_response[:response]
puts payment
using System;
using MercadoPago.Client.Common;
using MercadoPago.Client.Payment;
using MercadoPago.Config;
using MercadoPago.Resource.Payment;
MercadoPagoConfig.AccessToken = "YOUR_ACCESS_TOKEN";
var paymentRequest = new PaymentCreateRequest
{
TransactionAmount = decimal.Parse(Request["transactionAmount"]),
Token = Request["token"],
Description = Request["description"],
Installments = int.Parse(Request["installments"]),
PaymentMethodId = Request["paymentMethodId"],
NotificationUrl = "http://requestbin.fullcontact.com/1ogudgk1",
Payer = new PaymentPayerRequest
{
Email = Request["email"],
Identification = new IdentificationRequest
{
Type = Request["docType"],
Number = Request["docNumber"],
},
},
};
var client = new PaymentClient();
Payment payment = await client.CreateAsync(paymentRequest);
Console.WriteLine(payment.Status);
import mercadopago
sdk = mercadopago.SDK("ACCESS_TOKEN")
payment_data = {
"transaction_amount": float(request.POST.get("transaction_amount")),
"token": request.POST.get("token"),
"description": request.POST.get("description"),
"installments": int(request.POST.get("installments")),
"payment_method_id": request.POST.get("payment_method_id"),
"notification_url": "http://requestbin.fullcontact.com/1ogudgk1",
"payer": {
"email": request.POST.get("email"),
"identification": {
"type": request.POST.get("type"),
"number": request.POST.get("number")
}
}
}
payment_response = sdk.payment().create(payment_data)
payment = payment_response["response"]
print(payment)
curl -X POST \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/payments' \
-d '{
"transaction_amount": 100,
"token": "ff8080814c11e237014c1ff593b57b4d",
"description": "Blue shirt",
"installments": 1,
"payment_method_id": "visa",
"issuer_id": 310,
"notification_url": "http://requestbin.fullcontact.com/1ogudgk1",
"payer": {
"email": "test@test.com"
}
}'
- Implementa el receptor de notificaciones usando el siguiente cĂłdigo como ejemplo:
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.");
}
?>
- Una vez realizadas las configuraciones, Mercado Pago notificarĂĄ esa URL con dos parĂĄmetros cada vez que se cree o actualice un recurso:
Campo | DescripciĂłn |
topic | Identifica cuĂĄl es el recurso. Puede ser payment , chargebacks , merchant_order o point_integration_ipn . |
id | Es un identificador Ășnico del recurso notificado. |
Acciones necesarias después de recibir la notificación
Cuando recibes una notificaciĂłn en tu plataforma, Mercado Pago espera una respuesta para validar que esa recepciĂłn fue correcta. Para eso, debes devolver un HTTP STATUS 200 (OK)
o 201 (CREATED)
.
El tiempo de espera para esa confirmaciĂłn serĂĄ de 22 segundos. Si no se envĂa esta respuesta, el sistema entenderĂĄ que la notificaciĂłn no fue recibida y realizarĂĄ un nuevo intento de envĂo cada 15 minutos, hasta que reciba la respuesta. DespuĂ©s del tercer intento, el plazo serĂĄ prorrogado, pero los envĂos continuarĂĄn sucediendo.
Luego de responder la notificación, confirmando su recibimiento, puedes obtener toda la información sobre el recurso notificado haciendo una requisición al endpoint correspondiente. Para identificar qué endpoint debes utilizar, consulta la tabla debajo:
Tipo | URL | DocumentaciĂłn |
payment | https://api.mercadopago.com/v1/payments/[ID] | Obtener pago |
point_integration_ipn | https://api.mercadopago.com/point/integration-api/payment-intents/{paymentintentid} | Obtener intenciĂłn de pago |
merchant_orders | https://api.mercadopago.com/merchant_orders/[ID] | Obtener orden |
chargebacks | https://api.mercadopago.com/v1/chargebacks/[ID] | Obtener contracargo |
Con esta informaciĂłn podrĂĄs realizar las actualizaciones necesarias a tu plataforma, como actualizar un pago aprobado.