SupportLog in
DocsAPI ReferenceSDK ReferenceResourcesPayments ManagementChangelog

Legacy Webhooks

The payment webhook payloads sent to Hosted Checkout accounts that still run on the legacy flow.

These payloads apply only to accounts on the legacy payment flow. Accounts processed through the Direct API receive the standard webhooks described in Listen for webhooks.

Register your endpoint in the Dashboard under Developers → Webhooks, in each environment.

What you receive

NotificationWhen it is sent
Payment statusEach time the payment's transaction reaches Pending, Success or Declined.
  • There are no session-level webhooks: session.created, session.completed and session.expired are not sent.
  • Enrollment sessions create no payment, so they produce no notification.
  • The response object depends on the payment method. Do not rely on a fixed structure inside it.

Card payment — 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"
}

Card payment — 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"
}

A Pending notification has the same shape with "transaction_status": "Pending" and, for redirect-based methods, a response.redirect_url.

Alternative method (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" }
  }
}

Handling them

  • Match the webhook to your order with payment_id (returned when you created the session) or metadata.external_id.
  • Card notifications are flat; alternative-method notifications are wrapped in data. Check for data before reading transaction_status.
  • Respond 200 immediately, process idempotently, and confirm with Get a session before fulfilling.

Next steps

Legacy overview

What legacy means and how to move to 2.0.

Listen for webhooks

The webhooks of Hosted Checkout 2.0.

Was this page helpful?

On this page

What you receiveCard payment — SuccessCard payment — DeclinedAlternative method (OXXO Pay, Mercado Pago)Handling themNext steps