Sign in

v12

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-011518127.5 KB
Hosted Checkout

Create a Payment Session

Creates a new Hosted Checkout session. Tonder returns a URL for you to redirect your customer to complete the payment. The session tracks the overall payment state and can handle multiple payment attempts if the first one fails.

post/checkout/v1/sessions

Request body

amount_totalnumber required

Total charge amount

currency'MXN' required

Currency code

external_idstring

Unique order reference from the merchant. Used to visually identify/filter the order in dashboard

expires_atinteger

Unix timestamp (seconds). Must be 30 min to 24h in future. Default 24h

metadataobject

Additional metadata

success_urlstring uri

Redirect after successful payment

return_urlstring uri

Required if success_url is not set. If specified, used as fallback for all redirects

pending_urlstring uri

Redirect if payment is under review. Only applicable for future APM support

payment_method_typesstring[]

Defaults to ["card"]. Currently only card is supported

checkout_type'hosted'

Defaults to "hosted"

session_type'payment'

Defaults to "payment"

ui_config_versionstring

Version of the UI config. Defaults to "V1"

Example request

{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "amount_total": 35000,
  "currency": "MXN",
  "line_items": [
    {
      "name": "Product 1",
      "quantity": 1,
      "unit_price": 15000,
      "product_id": "prod-12345"
    }
  ],
  "external_id": "ORD-12345",
  "expires_at": 1751063448,
  "success_url": "https://my-store.com/order/success",
  "return_url": "https://my-store.com/checkout/complete",
  "payment_method_types": [
    "card"
  ],
  "checkout_type": "hosted",
  "session_type": "payment",
  "ui_config_version": "V1",
  "ui_config": {
    "branding": {
      "brand_color": "#1A2B3C"
    },
    "theme": {
      "shapes": "rounded"
    }
  }
}

Response

Session created successfully

idstring

Unique session identifier

urlstring uri

Redirect your customer to this URL to begin the payment

status'pending' | 'completed' | 'expired'

Session status

payment_idnumber

Associated payment ID

amount_totalnumber

Total amount to be charged

currencystring

Currency used

expires_atinteger

Expiration time (Unix timestamp in seconds)

external_idstring

Order reference from the merchant

session_typestring

Type of session

checkout_typestring

Checkout method

success_urlstring uri nullable

Success redirect URL

return_urlstring uri

Return/fallback redirect URL

pending_urlstring uri nullable

Pending redirect URL

metadataobject

Custom data sent by the merchant

payment_method_typesstring[]

Allowed payment methods

ui_configobject

UI configuration applied

ui_config_versionstring

Version of UI config

created_atinteger

Creation timestamp in milliseconds

modified_atinteger

Last modification timestamp in milliseconds

paid_atinteger nullable

Payment completion timestamp in milliseconds

transaction_status'Pending' | 'Success' | 'Declined' | 'Expired'

Result of transaction

providerstring

Gateway used

Example response

{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "pending",
  "payment_id": 41521,
  "amount_total": 35000,
  "currency": "MXN",
  "expires_at": 1751564943,
  "external_id": "ORD-12345",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_method_types": [
    "card"
  ],
  "ui_config_version": "V1",
  "created_at": 1751478543567,
  "modified_at": 1751478543567,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "transaction_status": "Pending",
  "provider": "tonder"
}