Webhook Events & Payloads

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:

Field	Type	Description
action	string	The event type (e.g., `session.created`, `session.completed`, `session.expired`).
type	string	The checkout type, always `checkout.hosted` for Hosted Checkout.
data	object	Event-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:

Field	Type	Description
id	string	The unique session ID.
url	string	The checkout URL where the customer completes payment.
amount_total	number	Total charge amount.
currency	string	Currency code (e.g., “MXN”).
status	string	Session status, will be `pending` for this event.
payment_id	number	The payment transaction ID.
transaction_status	string	Transaction status, will be `Pending` for this event.
created_at	number	Unix timestamp in milliseconds when the session was created.
customer	object	Customer details including `first_name`, `last_name`, and `email`.
metadata	object	Custom key-value pairs sent by the merchant in the session request.

View Full JSON Payload Example

{
  "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:

Field	Type	Description
id	string	The unique session ID.
url	string	The checkout URL where the customer completed payment.
amount_total	number	Total charge amount.
currency	string	Currency code (e.g., “MXN”).
status	string	Session status, will be `completed` for this event.
payment_id	number	The payment transaction ID.
transaction_status	string	Transaction status, will be `Success` for this event.
paid_at	number	Unix timestamp in milliseconds when the payment was completed.
customer	object	Customer details including `first_name`, `last_name`, and `email`.
metadata	object	Custom key-value pairs sent by the merchant in the session request.

View Full JSON Payload Example

{
  "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:

Field	Type	Description
id	string	The unique session ID.
url	string	The checkout URL that expired.
amount_total	number	Total charge amount.
currency	string	Currency code (e.g., “MXN”).
status	string	Session status, will be `expired` for this event.
payment_id	number	The payment transaction ID.
transaction_status	string	Transaction status, will be `Expired` for this event.
customer	object	Customer details including `first_name`, `last_name`, and `email`.
metadata	object	Custom key-value pairs sent by the merchant in the session request.

View Full JSON Payload Example

{
  "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:

Field	Type	Description
payment_id	string	The unique payment transaction ID.
session_id	string	The session ID this payment belongs to.
status	string	Transaction status (e.g., `Pending`, `Success`, `Declined`).
amount	number	Payment amount.
currency	string	Currency code (e.g., “MXN”).
payment_method_type	string	Payment method used (e.g., “card”).
created_at	string	ISO 8601 timestamp when the transaction was created.
card_details	object	Card information including `brand` and `last4` digits.
customer	object	Customer details including `name` and `email`.
metadata	object	Custom key-value pairs sent by the merchant in the session request.

View Full JSON Payload Example (Declined)

{
  "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"
    }
  }
}

Hosted Checkout Integration

Guides

Reference

Webhook Events & Payloads

Session Events

session.created

session.completed

session.expired

Payment Transaction Events

payment.transaction

​Session Events

​session.created

​session.completed

​session.expired

​Payment Transaction Events

​payment.transaction

Session Events

session.created

session.completed

session.expired

Payment Transaction Events

payment.transaction