Webhooks legacy

Los payloads de webhook de pago que se envían a las cuentas de Hosted Checkout que todavía operan con el flujo legacy.

Estos payloads aplican únicamente a las cuentas en el flujo de pago legacy. Las cuentas procesadas con la API Direct reciben los webhooks estándar descritos en Escuchar webhooks.

Registra tu endpoint en el Dashboard, en Developers → Webhooks, en cada entorno.

Qué recibes

Notificación	Cuándo se envía
Estado del pago	Cada vez que la transacción del pago llega a `Pending`, `Success` o `Declined`.

No hay webhooks a nivel de sesión: session.created, session.completed y session.expired no se envían.
Las sesiones de registro de tarjeta no crean ningún pago, así que no producen ninguna notificación.
El objeto response depende del método de pago. No dependas de una estructura fija dentro de él.

Pago con tarjeta — Success

{
  "transaction_reference": "20106223",
  "status": "Success",
  "transaction_status": "Success",
  "amount": 2.0,
  "currency": "MXN",
  "payment_id": 41529,
  "transaction_type": "PAYMENT",
  "provider": "tonder",
  "operation_date": "2025-07-02 19:48:36",
  "number_of_installments": 1,
  "number_of_payment_attempts": 1,
  "response": {
    "payment_method": "BANKCARD",
    "payment_data": {
      "amount": 2.0,
      "currency": "MXN",
      "id": "20106223",
      "is_3d": true,
      "status": "COMPLETED",
      "type": "PAYMENT"
    },
    "card_account": { "masked_pan": "400000...0085" }
  },
  "metadata": { "external_id": "ORD-001" },
  "checkout_id": "001f4182-b95e-42bd-bc94-06f8d8bcb582"
}

Pago con tarjeta — Declined

{
  "transaction_reference": "20106235",
  "status": "Declined",
  "transaction_status": "Declined",
  "amount": 2.0,
  "currency": "MXN",
  "payment_id": 41530,
  "transaction_type": "PAYMENT",
  "provider": "tonder",
  "response": {
    "payment_data": {
      "decline_code": "04",
      "decline_reason": "Declined by 3-D Secure",
      "id": "20106235",
      "is_3d": true,
      "status": "DECLINED"
    }
  },
  "metadata": { "external_id": "ORD-001" },
  "checkout_id": "ea37a030-02ad-4c55-8351-28455af8e6b7"
}

Una notificación Pending tiene la misma forma, con "transaction_status": "Pending" y, en los métodos basados en redirección, un response.redirect_url.

Método alternativo (OXXO Pay, Mercado Pago)

{
  "action": "payment",
  "type": "apm",
  "data": {
    "id": "742cd7ef-8ee2-421b-a418-f573494a1ae0",
    "transaction_reference": "2025070500035400001",
    "reference": "98002018925684",
    "transaction_status": "Success",
    "amount": 2,
    "currency_code": "MXN",
    "payment_id": 41714,
    "checkout_id": "b234ec24-4c33-4ab5-af07-98293b2fae32",
    "payment_method_name": "oxxopay",
    "operation_date": "2025-07-05T00:03:55.802Z",
    "transaction_type": "PAYMENT",
    "provider": "oxxopay",
    "metadata": { "external_id": "ORD-001" }
  }
}

Cómo manejarlos

Relaciona el webhook con tu pedido mediante el payment_id (devuelto cuando creaste la sesión) o metadata.external_id.
Las notificaciones de tarjeta son planas; las de métodos alternativos vienen envueltas en data. Revisa si existe data antes de leer transaction_status.
Responde 200 de inmediato, procesa de forma idempotente y confirma con Consultar una sesión antes de entregar el pedido.

Webhooks legacy

Qué recibes

Pago con tarjeta — Success

Pago con tarjeta — Declined

Método alternativo (OXXO Pay, Mercado Pago)

Cómo manejarlos

Siguientes pasos

Resumen de legacy

Escuchar webhooks

En esta página