Create a Payment Session

The request body that creates a payment session, field by field, and the URL it returns.

This is the main endpoint for initiating a Hosted Checkout payment. It creates a new payment session and returns a secure URL where your customer completes their payment.

POST https://api-stage.tonder.io/checkout/v1/sessions   # Sandbox
POST https://api.tonder.io/checkout/v1/sessions          # Production

How it works

Your server calls this endpoint with payment details (amount, items, customer info).
Tonder creates a secure session and returns a checkout URL.
You redirect your customer to this URL.
The customer completes the payment on Tonder's hosted page.
The customer is redirected back to your success_url or return_url.

Include the x-idempotency-key header to prevent duplicate sessions (see Idempotency) and the ui_config object to customize the page (see Customize the checkout).

The payment_method_types field defaults to ["card"]. Accepted values: card, mercadopago, oxxopay, spei, safetypayCash, safetypayTransfer, neosurf.

API reference

Authorization

Authorization

Authorization<token>

Tu API key con prefijo Token , p. ej. Token <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customer*

amount_total*number

Total charge amount

currency*string

Currency code

line_items*array<>

List of order items

external_id?string

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

expires_at?integer

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

metadata?

Additional metadata

success_url?string

Redirect after successful payment

return_url?string

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

pending_url?string

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

payment_method_types?array<>

Payment methods offered on the hosted page. Defaults to ["card"].

checkout_type?string

Defaults to "hosted"

session_type?string

Defaults to "payment"

ui_config_version?string

Version of the UI config. Defaults to "V1"

ui_config?

UI configuration for Hosted Checkout customization

Response Body

`application/json`

curl -X POST "https://example.com/checkout/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "first_name": "John",      "last_name": "Doe",      "email": "john.doe@example.com"    },    "amount_total": 350,    "currency": "MXN",    "line_items": [      {        "name": "Product 1",        "quantity": 1,        "unit_price": 150,        "product_id": "prod-001"      },      {        "name": "Product 2",        "quantity": 2,        "unit_price": 100,        "product_id": "prod-002"      }    ],    "return_url": "https://my-store.com/checkout/complete",    "external_id": "ORD-12345"  }'

{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "pending",
  "payment_id": 41521,
  "amount_total": 350,
  "currency": "MXN",
  "expires_at": 1751564943,
  "external_id": "ORD-12345",
  "session_type": "payment",
  "checkout_type": "hosted",
  "return_url": "https://my-store.com/checkout/complete",
  "metadata": {},
  "payment_method_types": [
    "card"
  ],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751478543567,
  "modified_at": 1751478543567,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "line_items": [
    {
      "name": "Product 1",
      "quantity": 1,
      "unit_price": 150,
      "product_id": "prod-001"
    }
  ],
  "transaction_status": "Pending",
  "provider": "tonder"
}

The session starts in pending and transitions to a final state. See the full values in the Reference.

Next steps

Quickstart

The full four-step flow.

Check the status

Retrieve the session or payment status.

Reference

Statuses, identifiers, and webhook events.

API Reference

The full API index.