Webhooks
Webhook (también conocido como devolución de llamada web) es un método simple que facilita que una aplicación o sistema proporcione información en tiempo real cada vez que ocurre un evento, es decir, es una forma de recibir datos pasivamente entre dos sistemas a través de un HTTP POST
.
Las notificaciones de webhook se pueden configurar para una o más aplicaciones creadas en su Dashboard.
Una vez configurado, el Webhook se enviará siempre que se produzcan uno o más eventos registrados, evitando un trabajo de búsqueda cada minuto en busca de una respuesta y, en consecuencia, una sobrecarga del sistema y pérdida de datos siempre que se presente alguna situación. Luego de recibir una notificación en su plataforma, Mercado Pago esperará una respuesta para validar si la recibió correctamente.
En esta documentación te explicaremos la configuración necesaria para recibir mensajes (a través del Dashboard o al momento de crear pagos), además de mostrar las acciones necesarias que debes realizar para que Mercado Pago valide que las notificaciones fueron recibidas correctamente.
Configuración a través del Dashboard
A continuación explicaremos cómo indicar las URLs que serán notificadas y cómo configurar los eventos para los que se recibirán notificaciones.
- Primero, se debe crear una aplicación en la página de inicio de su Dashboard.
- Con la aplicación creada, ve a la pestaña Notificaciones de Webhooks en tu Panel de control y configura las URLs de producción y prueba de las que se recibirán notificaciones.
- También podrás experimentar y probar si la URL indicada está recibiendo notificaciones correctamente, pudiendo verificar la solicitud, la respuesta dada por el servidor y la descripción del evento.
- Si necesitas identificar varias cuentas, al final de la URL indicada puedes indicar el parámetro
?cliente=(nommbredelvendedor) endpoint
para identificar a los vendedores. - A continuación, selecciona los eventos de los que recibirás notificaciones en formato
json
a través de unHTTP POST
a la URL especificada anteriormente. Un evento es cualquier tipo de actualización del objeto informado, incluidos los cambios de estado o atributos. Vea los eventos que se pueden configurar en la siguiente tabla.
Tipo de notificación | Acción | Descripción |
payment | payment.created | Creación de pagos |
payment | payment.updated | Actualización de pago |
mp-connect | application.deauthorized | Desvinculación de cuenta |
mp-connect | application.authorized | Vinculación de cuenta |
subscription_preapproval | created - updated | Suscripción |
subscription_preapproval_plan | created - updated | Plan de suscripción |
subscription_authorized_payment | created - updated | Pago recurrente de una suscripción |
point_integration_wh | state_FINISHED | Intento de pago finalizado |
point_integration_wh | state_CANCELED | Intento de pago cancelado |
point_integration_wh | state_ERROR | Ocurrió un error al procesar el intento de pago |
delivery | delivery.updated | Datos de envío y actualización de pedidos |
Configuración al crear pagos
Es posible configurar la URL de notificación de forma más específica para cada pago utilizando el campo notification_url
. Ve a continuación cómo hacer esto 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.
<?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"
}
}'
- Implemente el receptor de notificaciones usando el siguiente código como ejemplo:
php
<?php
MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
switch($_POST["type"]) {
case "payment":
$payment = MercadoPago\Payment::find_by_id($_POST["data"]["id"]);
break;
case "plan":
$plan = MercadoPago\Plan::find_by_id($_POST["data"]["id"]);
break;
case "subscription":
$plan = MercadoPago\Subscription::find_by_id($_POST["data"]["id"]);
break;
case "invoice":
$plan = MercadoPago\Invoice::find_by_id($_POST["data"]["id"]);
break;
case "point_integration_wh":
// $_POST contiene la informaciòn relacionada a la notificaciòn.
break;
}
?>
- Una vez que se hayan realizado los ajustes necesarios, la notificación a través de Webhook tendrá el siguiente formato:
json
{
"id": 12345,
"live_mode": true,
"type": "payment",
"date_created": "2015-03-25T10:04:58.396-04:00",
"user_id": 44444,
"api_version": "v1",
"action": "payment.created",
"data": {
"id": "999999999"
}
}
Esto indica que el pago 999999999 fue creado para el usuario 44444 en modo de producción con API versión V1 y que este evento ocurrió en la fecha 2016-03-25T10: 04: 58.396-04: 00.
Atributo | Descripción |
id | ID de la notificación |
live_mode | Indica si la URL ingresada es válida. |
type | Tipo de notificacion recebida (payments, mp-connect, subscription etc) |
date_created | Fecha de creación del recurso (payments, mp-connect, subscription etc) |
user_id | UserID del vendedor |
api_version | Indica si es una notificación duplicada o no |
action | Tipo de notificación recibida, indicando si es la actualización de un recurso o bien la creación de un nuevo |
data - id | ID del payment o merchant_order |
attempts (delivery) | Número de veces que se envió una notificación |
received (delivery) | Fecha de creación del recurso |
resource (delivery) | Tipo de notificación recibida, indicando si se trata de una actualización de una característica o de la creación de una nueva |
sent (delivery) | Fecha de envío de la notificación |
topic (delivery) | Tipo de notificación recibida |
- Si deseas recibir notificaciones solo de Webhook y no de IPN, puedes agregar en el
notification_url
el parámetrosource_news=webhooks
. Por ejemplo: https://www.yourserver.com/notifications?source_news=webhooks
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 la recibiste correctamente. Para eso, debes devolver un HTTP STATUS 200 (OK)
o 201 (CREATED)
. Si no se envía esta respuesta, se entenderá que no ha recibido la notificación y se realizará un nuevo intento de envío hasta que reciba la respuesta.
En la siguiente tabla puedes encontrar los principales eventos, plazos y tiempo de espera para recibir nuevos intentos de notificación.
Evento | Plazo después del primer envío | Tiempo de espera de confirmación |
Envío | - | 22 segundos |
Primer intento | 15 minutos | 5 segundos |
Segundo intento | 30 minutos | 5 segundos |
Tercer intento | 6 horas | 5 segundos |
Cuarto intento | 48 horas | 5 segundos |
Quinto intento | 96 horas | 5 segundos |
Luego de devolver la notificación y confirmar su recepción, obtendrás la información completa del recurso notificado accediendo al endpoint de la API correspondiente:
Tipo | URL | Documentación |
payment | https://api.mercadopago.com/v1/payments/[ID] | ver documentación |
subscription_preapproval | https://api.mercadopago.com/preapproval | ver documentación |
subscription_preapproval_plan | https://api.mercadopago.com/preapproval_plan | ver documentación |
subscription_authorized_payment | https://api.mercadopago.com/authorized_payments | ver documentación |
point_integration_wh | - | ver documentación |
delivery | - | ver documentación |
Con esta información podrás realizar las actualizaciones necesarias a tu plataforma, como actualizar un pago aprobado.