Recursos para IA

Configurar notificaciones de pago

Las notificaciones Webhooks, también conocidas como devoluciones de llamada web, son mensajes HTTP que Mercado Pago envía a tu servidor cuando ocurre un evento específico en tu integración. En lugar de que tu sistema realice consultas constantes para verificar actualizaciones, los Webhooks transmiten los datos de forma automática mediante una solicitud HTTPS POST.

Configurar Webhooks

Sigue los pasos a continuación para recibir notificaciones en tu integración con Checkout Pro. Una vez configuradas, las notificaciones Webhook se enviarán siempre que ocurra cualquier actualización sobre el tópico reportado, incluyendo creación y actualización de orders y procesamiento de transacciones.

Ingresa a Integraciones y selecciona la aplicación integrada con Checkout Pro para la que deseas activar las notificaciones.

Vista general de Integraciones

En el menú lateral, selecciona Configuración de Webhooks.
En el switch Prueba / Producción de la parte superior, selecciona Prueba e ingresa la URL HTTPS para recibir notificaciones de prueba. Si quieres configurar notificaciones de producción, selecciona Producción e ingresa la URL HTTPS de producción.

En caso de ser necesario identificar múltiples cuentas, agrega el parámetro ?client=(nombredelvendedor) al final de la URL indicada para identificar a los vendedores.

Selecciona el evento Order (Mercado Pago) para recibir notificaciones, que serán enviadas en formato JSON a través de un HTTPS POST a la URL configurada para el entorno correspondiente.

Configuración de Webhooks de Checkout Pro con Orders

Por último, haz clic en Guardar. Esto generará una firma secreta exclusiva para la aplicación, que permitirá validar la autenticidad de las notificaciones recibidas y comprobar que hayan sido enviadas por Mercado Pago. La firma no tiene plazo de caducidad y su renovación periódica no es obligatoria, aunque sí recomendada. Para renovarla, haz clic en Restablecer firma secreta.

Simular la recepción de la notificación

Para garantizar que las notificaciones sean configuradas correctamente, es necesario simular su recepción. Para hacerlo, sigue el paso a paso a continuación.

Después de configurar tus Webhooks, haz clic en Simular notificación.
En la pantalla de simulación, selecciona la URL que se va a probar.
A continuación, elige el tipo de evento e ingresa la identificación que se enviará en el cuerpo de la notificación (Data ID).

Simulación de una notificación Webhook

Por último, haz clic en Enviar prueba para verificar la solicitud, la respuesta proporcionada por el servidor y la descripción del evento. Recibirás una respuesta según el ejemplo a continuación, que representa el body de la notificación recibida en tu servidor.

json
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "5852534070406015",
  "data": {
    "currency_id": "CLP",
    "external_reference": "ext_ref_manual_full_test",
    "id": "ORDTST01M4V4VSXCTN8ZN1FJ02KKMFGE",
    "items": [
      {
        "external_code": "ITEM-001",
        "quantity": 1
      }
    ],
    "status": "processed",
    "status_detail": "accredited",
    "total_amount": "4500",
    "total_paid_amount": "4500",
    "transactions": {
      "payments": [
        {
          "amount": "4500",
          "attempt_number": 1,
          "id": "PAY01M4V4XX5CXZ6KF1P3DEMX83VY",
          "paid_amount": "4500",
          "payment_method": {
            "id": "master",
            "installments": 1,
            "type": "credit_card"
          },
          "reference": {
            "id": "183961436800"
          },
          "status": "processed",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "online",
    "version": 1
  },
  "date_created": "2026-10-13T17:28:26.540980984Z",
  "live_mode": false,
  "type": "order",
  "user_id": "3431137176"
}

Si por algún motivo no estás recibiendo las notificaciones de Mercado Pago, puedes alternativamente obtener la información sobre el recurso que no fue notificado enviando una solicitud /v1/orders/{order_id}GET. El uso de este método no es recomendado, por lo que adicionalmente sugerimos entrar en contacto con Soporte.

Monitorear notificaciones

Para consultar el funcionamiento de las notificaciones, abre la aplicación y, en Inicio, selecciona la pestaña Webhooks. Utiliza el switch Prueba / Producción para consultar las notificaciones del entorno seleccionado.

En esta pantalla puedes filtrar los envíos, consultar su fecha, estado de entrega, acción, evento e ID del recurso, y revisar las métricas de entrega y tiempo de respuesta. En Prueba, los datos se actualizan en tiempo real.

Monitoreo de notificaciones Webhook

Para consultar los datos del envío y el cuerpo de la notificación, selecciona una notificación de la tabla para abrir su detalle.

Detalle de una notificación Webhook

Para reenviar una o varias notificaciones, selecciónalas en la tabla y haz clic en Reenviar notificaciones.

Validar el origen de la notificación

La validación del origen de una notificación es fundamental para asegurar la seguridad y la autenticidad de la información recibida. Este proceso ayuda a prevenir fraudes y garantiza que solo las notificaciones legítimas sean procesadas.

Mercado Pago enviará a tu servidor una notificación similar al ejemplo a continuación para una alerta del tópico order. En este ejemplo, se incluye la notificación completa, que contiene los query params, el body y el header de la notificación.

Query params: Son parámetros de consulta que acompañan la URL. En el ejemplo, tenemos data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 y type=order.
Body: El cuerpo de la notificación contiene información detallada sobre el evento, como action, api_version, application_id, date_created, id, live_mode, type, user_id y data.
Header: El encabezado contiene metadatos importantes, incluyendo la firma secreta de la notificación x-signature.

http
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Length: 177
Content-Type: application/json
Newrelic: eyJ2IjpbMCwxXSwiZCI6eyJ0eSI6IkFwcCIsImFjIjoiOTg5NTg2IiwiYXAiOiI5NjA2MzYwOTQiLCJ0eCI6ImY4MzljZjg4ODg2MGRmZTIiLCJ0ciI6ImMwOGMwZGMyMjNjZDY2YjJkZWQwMjUxZmYxNWNiNGQ1IiwicHIiOjEuMjUwMzIsInNhIjp0cnVlLCJ0aSI6MTc0Mjg0MjU4MDE2NCwiaWQiOiIxOGI2NDcxNjNkNzI3NjU4IiwidGsiOiIxNzA5NzA3In19=
Traceparent: 00-c08c0dc223cd66b2ded0251ff15cb4d5-18b647163d727658-01
Tracestate: 1709707@nr=0-0-989586-960636094-18b647163d727658-f839cf888860dfe2-1-1.250320-1742842580164
User-Agent: restclient-node/4.15.3
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
X-Socket-Timeout: 22000
{"action":"order.processed","api_version":"v1","application_id":"123456","date_created":"2025-08-07T18:54:40.851374414Z","id":"123456","live_mode":true,"type":"order","user_id":123456,"data":{"id":"ORD01JYH1Z1YJN4HZ8J3Q0RB3YP6D"}}

A partir de la notificación Webhook recibida, podrás validar la autenticidad de su origen. Mercado Pago siempre incluirá la clave secreta en las notificaciones Webhooks que se recibirán, lo que permitirá validar su autenticidad. Esta clave será enviada en el header x-signature, que será similar al ejemplo a continuación.

plain
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar la validación, es necesario extraer la clave contenida en el header y compararla con la clave proporcionada para tu aplicación en Configuración de Webhooks.

Sigue uno de los enfoques a continuación para validar la autenticidad de la notificación.

El SDK oficial implementa verificación de firma basada en HMAC (HMAC-based Webhook Signature Verification) para autenticar el origen de cada notificación recibida.

Para obtener tu clave secreta (secret), abre la aplicación y, en el menú lateral, selecciona Configuración de Webhooks. Luego, revela la Firma secreta.

<?php
use MercadoPago\Webhook\WebhookSignatureValidator;
use MercadoPago\Exceptions\InvalidWebhookSignatureException;

try {
    WebhookSignatureValidator::validate(
        $_SERVER['HTTP_X_SIGNATURE'],
        $_SERVER['HTTP_X_REQUEST_ID'],
        $_GET['data_id'],
        $secret
    );
    http_response_code(200);
} catch (InvalidWebhookSignatureException $e) {
    http_response_code(401);
}

import { WebhookSignatureValidator, InvalidWebhookSignatureError } from 'mercadopago';

try {
    WebhookSignatureValidator.validate({
        xSignature: req.headers['x-signature'],
        xRequestId: req.headers['x-request-id'],
        dataId:     req.query['data.id'],
        secret,
    });
    res.sendStatus(200);
} catch (err) {
    if (err instanceof InvalidWebhookSignatureError) res.status(401).end();
    else throw err;
}

from mercadopago.webhook import WebhookSignatureValidator, InvalidWebhookSignatureError

try:
    WebhookSignatureValidator.validate(
        request.headers.get("x-signature"),
        request.headers.get("x-request-id"),
        request.args.get("data.id"),
        secret,
    )
    return "", 200
except InvalidWebhookSignatureError:
    return "", 401

import "github.com/mercadopago/sdk-go/pkg/webhook"

err := webhook.ValidateSignature(
    r.Header.Get("x-signature"),
    r.Header.Get("x-request-id"),
    r.URL.Query().Get("data.id"),
    secret,
)
if err != nil {
    w.WriteHeader(http.StatusUnauthorized)
    return
}
w.WriteHeader(http.StatusOK)

using MercadoPago.Error;
using MercadoPago.Webhook;

try {
    WebhookSignatureValidator.Validate(
        xSignature: Request.Headers["x-signature"],
        xRequestId: Request.Headers["x-request-id"],
        dataId:     Request.Query["data.id"],
        secret:     secret);
    return Ok();
} catch (InvalidWebhookSignatureException) {
    return Unauthorized();
}

import com.mercadopago.webhook.WebhookSignatureValidator;
import com.mercadopago.exceptions.MPInvalidWebhookSignatureException;

try {
    WebhookSignatureValidator.validate(
        request.getHeader("x-signature"),
        request.getHeader("x-request-id"),
        request.getParameter("data.id"),
        secret);
    response.setStatus(200);
} catch (MPInvalidWebhookSignatureException e) {
    response.setStatus(401);
}

require 'mercadopago/webhook/validator'

begin
    Mercadopago::Webhook::Validator.validate(
        request.headers['x-signature'],
        request.headers['x-request-id'],
        request.params['data.id'],
        secret
    )
    head :ok
rescue Mercadopago::Webhook::InvalidWebhookSignatureError
    head :unauthorized
end

Acciones necesarias tras 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 ello, debes devolver un HTTP STATUS 200 (OK) o 201 (CREATED).

El tiempo de espera para esa confirmación será de 22 segundos. Si esa confirmación no es enviada, 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 ocurriendo.

sequenceDiagram
    participant MercadoPago as Mercado Pago
    participant Integrador as Integrador

    MercadoPago->>Integrador: intento: 1. Retraso: 0 minutos
    MercadoPago->>Integrador: intento: 2. Retraso: 15 minutos
    MercadoPago->>Integrador: intento: 3. Retraso: 30 minutos
    MercadoPago->>Integrador: intento: 4. Retraso: 6 horas
    MercadoPago->>Integrador: intento: 5. Retraso: 48 horas
    MercadoPago->>Integrador: intento: 6. Retraso: 96 horas
    MercadoPago->>Integrador: intento: 7. Retraso: 96 horas
    MercadoPago->>Integrador: intento: 8. Retraso: 96 horas

Después de responder a la notificación y confirmar su recepción, puedes obtener toda la información sobre la order notificada enviando una solicitud al endpoint /v1/orders/{order_id}GET.

Con esa información, podrás realizar las actualizaciones necesarias en tu plataforma, como actualizar un pago aprobado.

AnteriorSwiftIntegra Checkout Pro en una aplicación mobile utilizando Swift.

PróximoConfigurar notificaciones opcionalesConfigura notificaciones opcionales para recibir alertas sobre otros eventos de tu integración con Checkout Pro.