Recursos para IA

Configurar notificaciones de Perfiles de Pago

Las notificaciones Webhooks de Perfiles de Pago notifican a tu aplicación en tiempo real cada vez que un perfil vinculado a tu integración sufre un cambio relevante. En lugar de consultar la API periódicamente, recibes las actualizaciones en el momento en que ocurren mediante un HTTP POST.

De esta manera, es posible detectar cuando un perfil alcanza el estado ready para habilitar el flujo de cobros recurrentes, realizar las acciones necesarias ante la inactivación o cancelación de un método de pago asociado a un perfil y mantener tu sistema siempre sincronizado con el estado real.

    flowchart TD
        A[Cambio en el perfil] --> B{Verifica elegibilidad}
        B -->|No elegible| C[Evento descartado]
        B -->|Elegible| D["POST {tu-url} con payload JSON"]
        D --> E[Tu aplicación responde HTTP 200]
        E --> F[Procesa el evento de forma asíncrona]

Configurar Webhooks

Sigue el paso a paso a continuación para configurar las notificaciones de Perfiles de Pago.

Accede a Integraciones y selecciona la aplicación para la que deseas activar las notificaciones.

La aplicación en la que se configuren las notificaciones debe coincidir con la responsable de la creación del perfil.

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.
Selecciona el evento Perfil de Pago (payment_profile) para recibir notificaciones de cambios en el perfil.

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 estén configuradas correctamente, simula su recepción siguiendo el paso a paso a continuación.

Después de configurar la URL y el evento, haz clic en Guardar.
Luego, haz clic en Simular notificación para verificar que la URL indicada está recibiendo las notificaciones correctamente.
En la pantalla de simulación, selecciona la URL que se va a probar.
Elige el tipo de evento Perfil de Pago e ingresa el ID del perfil que se enviará en el cuerpo de la notificación (Data ID).
Por último, haz clic en Enviar prueba para verificar la solicitud, la respuesta del servidor y la descripción del evento.

Monitorear notificaciones

Para consultar las notificaciones de Perfiles de Pago, 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.

Allí puedes filtrar los envíos, consultar su fecha, estado de entrega, acción, evento e ID del recurso, revisar las métricas de entrega y tiempo de respuesta, abrir el detalle para ver el cuerpo de la notificación y reenviarla cuando sea necesario. En Prueba, los datos se actualizan en tiempo real.

Monitoreo de notificaciones Webhook

Validar 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 payment_profile.

json
{
  "id": "abc123def456",
  "type": "payment_profile",
  "action": "payment_profile.updated",
  "version": 3,
  "date_created": "2026-01-10T10:00:00.000+0000",
  "live_mode": true,
  "collector_id": "123456789",
  "application_id": "1234567890",
  "data": {
    "date_last_updated": "2026-03-27T14:30:00.000+0000",
    "status": "ready",
    "payment_methods": [
      {
        "unique_id": "pm_001",
        "type": "credit_card",
        "status": "ready",
        "default_method": true,
        "card_id": 111222333
      }
    ],
    "previous_attributes": {
      "status": "pending",
      "payment_method": {
        "unique_id": "pm_001",
        "type": "credit_card",
        "status": "rejected",
        "default_method": false,
        "card_id": 111222333
      }
    }
  }
}

Campo	Tipo	Presencia	Descripción
`id`	string	Siempre	Identificador del perfil de pago, devuelto por la API al momento de su creación.
`type`	string	Siempre	Siempre `payment_profile`.
`action`	string	Siempre	Siempre `payment_profile.updated`, que indica que un atributo relevante del perfil fue modificado, ya sea su status, medio de pago, o ambos.
`version`	integer	Siempre	Contador incremental de notificaciones para este perfil. Úsalo para ordenar eventos fuera de secuencia.
`date_created`	string	Siempre	Fecha de creación del perfil (ISO 8601).
`live_mode`	boolean	Siempre	`true` en producción, `false` en pruebas.
`collector_id`	string	Siempre	ID del vendedor asociado al perfil.
`application_id`	string	Siempre	ID de la aplicación integradora que originó el perfil.
`data`	object	Siempre	Detalles del cambio ocurrido.
`data.date_last_updated`	string	Siempre	Fecha y hora exacta del cambio en el perfil, en formato ISO 8601.
`data.status`	string	Presente solo si el status fue modificado	Nuevo status del perfil.
`data.payment_methods`	array	Presente solo si hubo cambio en un método de pago.	Información actual de los medios de pago afectados. Incluye su identificador único (`unique_id`), el tipo de medio de pago (`credit_card`, `debit_card`, `prepaid_card`, `bank_transfer`), su `status` actual y si está definido como medio de pago predeterminado para cobros (`default_method`). En caso de que el medio de pago sea una tarjeta, también estará presente su ID (`card_id`).
`data.previous_attributes`	object	Ausente en adiciones de nuevos medios de pago.	Información previa de los atributos que cambiaron en el perfil de pago.
`previous_attributes.status`	string	Condicional	Estado anterior del perfil de pago.
`previous_attributes.payment_method`	object	Condicional	Estado anterior del medio de pago afectado.

Para consultar los valores posibles de data.status y data.payment_methods[*].status y las acciones recomendadas para cada uno, consulta Estados del perfil y del medio de pago.

A partir de la notificación recibida, podrás validar la autenticidad de su origen a través de la clave secreta. Esta clave será enviada en el header x-signature, con el siguiente formato:

plain
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar la validación, es necesario extraer la clave contenida en el header y compararla con la clave otorgada 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.

Los SDKs oficiales implementan 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 después de recibir la notificación

Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recepción fue correcta. Para eso, devuelve un HTTP STATUS 200 o 201 dentro de los 22 segundos siguientes a la recepción.

Recomendamos que primero respondas con un 200 o 201, y que luego proceses la notificación en el servidor, para evitar notificaciones duplicadas.

Si no se envía esta respuesta, el sistema realizará nuevos intentos de envío cada 15 minutos. Después de los primeros fallos, el intervalo se amplía progresivamente, pero las entregas continúan hasta que la notificación sea confirmada.

Luego de confirmar la recepción, procesa el evento de forma asíncrona. Si tu integración depende del estado completo del perfil, consulta la API enviando una solicitud a /v1/customers/{customerId}/payment-profiles/{id}GET con el campo id recibido en la notificación.

Nunca deduzcas el estado completo del perfil exclusivamente a partir de los datos de la notificación, pues esta envía solo los campos que sufrieron modificaciones.

AnteriorConfigurar notificaciones de ordersConfigura la recepción de notificaciones de Mercado Pago para mantener actualizadas las orders en tu sistema.

PróximoProbar la integraciónAprende a simular el flujo de pago y procesa un cobro de pruebas.