Skip to main content
When you set up a webhook endpoint, Tonder will send POST requests with an event payload when key actions occur. All webhook payloads follow this structure: 
{
  "action": "session.created",
  "type": "checkout.hosted",
  "data": {
    // ... object related to the event
  }
}
The table below describes the top-level fields present in every webhook:
FieldTypeDescription
actionstringThe event type (e.g., session.created, session.completed, session.expired).
typestringThe checkout type, always checkout.hosted for Hosted Checkout.
dataobjectEvent-specific data containing session or transaction details.
Order Reference in WebhooksThe external_id sent in the session creation request is visible in the Tonder dashboard as Order ID and in transaction reports as Business Transaction ID, but it is not returned in webhook payloads. To receive your order reference in a webhook, include it inside the metadata object — in addition to the existing external_id field — when creating the session. It will then be available under data.metadata in the webhook payload.
{
  "metadata": {
    "external_id": "YOUR-ORDER-ID"
  }
}

​
Session Events

​
session.created

Sent when a new checkout session is successfully created. The table below describes the fields in the data object for this event:
FieldTypeDescription
idstringThe unique session ID.
urlstringThe checkout URL where the customer completes payment.
amount_totalnumberTotal charge amount.
currencystringCurrency code (e.g., “MXN”).
statusstringSession status, will be pending for this event.
payment_idnumberThe payment transaction ID.
transaction_statusstringTransaction status, will be Pending for this event.
created_atnumberUnix timestamp in milliseconds when the session was created.
customerobjectCustomer details including first_name, last_name, and email.
metadataobjectCustom key-value pairs sent by the merchant in the session request.
{
  "action": "session.created",
  "type": "checkout.hosted",
  "data": {
    "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
    "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
    "amount_total": 5000,
    "currency": "MXN",
    "status": "pending",
    "payment_id": 41521,
    "transaction_status": "Pending",
    "created_at": 1751478543567,
    "customer": {
      "first_name": "New",
      "last_name": "Customer",
      "email": "new@example.com"
    },
    "metadata": {
      "external_id": "ORD-A1B2-NEW"
    }
  }
}

​
session.completed

Sent when a session is successfully paid for and completed. This is the primary event for confirming a successful order. The table below describes the fields in the data object for this event:
FieldTypeDescription
idstringThe unique session ID.
urlstringThe checkout URL where the customer completed payment.
amount_totalnumberTotal charge amount.
currencystringCurrency code (e.g., “MXN”).
statusstringSession status, will be completed for this event.
payment_idnumberThe payment transaction ID.
transaction_statusstringTransaction status, will be Success for this event.
paid_atnumberUnix timestamp in milliseconds when the payment was completed.
customerobjectCustomer details including first_name, last_name, and email.
metadataobjectCustom key-value pairs sent by the merchant in the session request.
{
  "action": "session.completed",
  "type": "checkout.hosted",
  "data": {
    "id": "cs_97_41528_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
    "url": "https://stage-payflow.tonder.io/checkout/cs_97_41528_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
    "amount_total": 15000,
    "currency": "MXN",
    "status": "completed",
    "payment_id": 41528,
    "transaction_status": "Success",
    "paid_at": 1751478550234,
    "customer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com"
    },
    "metadata": {
      "external_id": "ORD-G7H8-PAID"
    }
  }
}

​
session.expired

Sent when a pending session expires without a successful payment (e.g., the customer abandoned the checkout). The table below describes the fields in the data object for this event:
FieldTypeDescription
idstringThe unique session ID.
urlstringThe checkout URL that expired.
amount_totalnumberTotal charge amount.
currencystringCurrency code (e.g., “MXN”).
statusstringSession status, will be expired for this event.
payment_idnumberThe payment transaction ID.
transaction_statusstringTransaction status, will be Expired for this event.
customerobjectCustomer details including first_name, last_name, and email.
metadataobjectCustom key-value pairs sent by the merchant in the session request.
{
  "action": "session.expired",
  "type": "checkout.hosted",
  "data": {
    "id": "cs_97_41529_k1j2h3g4f5e6d7c8b9a0",
    "url": "https://stage-payflow.tonder.io/checkout/cs_97_41529_k1j2h3g4f5e6d7c8b9a0",
    "amount_total": 2500,
    "currency": "MXN",
    "status": "expired",
    "payment_id": 41529,
    "transaction_status": "Expired",
    "customer": {
      "first_name": "Tom",
      "last_name": "Abandoned",
      "email": "tom@example.com"
    },
    "metadata": {
      "external_id": "ORD-L9M8-EXPIRED"
    }
  }
}

​
Payment Transaction Events

​
payment.transaction

Sent when a payment transaction status changes (e.g., Pending, Success, Declined). A single session may have multiple payment.transaction events if the user retries.
While session.completed tells you the order is paid, payment.transaction gives you details about each attempt.
The table below describes the fields in the data object for this event:
FieldTypeDescription
payment_idstringThe unique payment transaction ID.
session_idstringThe session ID this payment belongs to.
statusstringTransaction status (e.g., Pending, Success, Declined).
amountnumberPayment amount.
currencystringCurrency code (e.g., “MXN”).
payment_method_typestringPayment method used (e.g., “card”).
created_atstringISO 8601 timestamp when the transaction was created.
card_detailsobjectCard information including brand and last4 digits.
customerobjectCustomer details including name and email.
metadataobjectCustom key-value pairs sent by the merchant in the session request.
{
  "event_type": "payment.transaction",
  "data": {
    "payment_id": 41522,
    "session_id": "cs_97_41522_f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8",
    "status": "Declined",
    "amount": 7500,
    "currency": "MXN",
    "payment_method_type": "card",
    "created_at": "2025-10-20T15:00:00Z",
    "card_details": {
      "brand": "mastercard",
      "last4": "5555"
    },
    "customer": {
      "name": "Test Retry",
      "email": "retry@example.com"
    },
    "metadata": {
      "external_id": "ORD-F1G2-RETRY"
    }
  }
}