Create a Session

Call this endpoint from your backend each time a customer is ready to pay. It creates one checkout session — for one payment or one card enrollment — and returns the url to send the customer to.

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

How it works

1. Your server calls this endpoint with the customer, the amount and the items.
2. Tonder creates the session and, for payment sessions, the payment. You receive the checkout url and the payment_id.
3. You redirect the customer to the url, or embed it.
4. The customer pays on Tonder's page. They can retry in the same session.
5. The customer returns to your site, and you confirm the result with webhooks or by reading the session.

A session is single-use and valid for at most 24 hours. Its amount, currency and line items cannot be changed — create a new session instead.

Headers

Body

Customer

Line items

Example

curl -X POST 'https://api-stage.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_TEST_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: ORD-001-attempt-1' \
  -d '{
    "customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
    "amount_total": 150.00,
    "currency": "MXN",
    "external_id": "ORD-001",
    "line_items": [
      { "name": "Premium Plan", "quantity": 1, "unit_price": 150.00, "product_id": "plan-premium-01" }
    ],
    "payment_method_types": ["card", "saved_cards", "oxxopay"],
    "submit_type": "pay",
    "locale": "en",
    "return_url": "https://your-store.com/checkout/complete",
    "metadata": { "external_id": "ORD-001" }
  }'

curl -X POST 'https://api.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: ORD-001-attempt-1' \
  -d '{
    "customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
    "amount_total": 150.00,
    "currency": "MXN",
    "external_id": "ORD-001",
    "line_items": [
      { "name": "Premium Plan", "quantity": 1, "unit_price": 150.00, "product_id": "plan-premium-01" }
    ],
    "payment_method_types": ["card", "saved_cards", "oxxopay"],
    "submit_type": "pay",
    "locale": "en",
    "return_url": "https://your-store.com/checkout/complete",
    "metadata": { "external_id": "ORD-001" }
  }'

{
  "id": "cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "status": "pending",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_id": 41528,
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "en",
  "amount_total": 150.00,
  "currency": "MXN",
  "external_id": "ORD-001",
  "return_url": "https://your-store.com/checkout/complete",
  "payment_method_types": ["card", "saved_cards", "oxxopay"],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751483563558,
  "modified_at": 1751483563558,
  "expires_at": 1751569963
}

What the response gives you

The full list of identifiers and statuses is in the Reference.

Payment attempts

A customer can try to pay more than once in the same session — a card is declined and they retry with another one. The session keeps only the latest attempt: transaction_status (and direct_transaction_id on Direct API accounts) is replaced on every new attempt, so a first Declined can become Success. payment_id stays the same for the whole session, so every attempt belongs to the same payment.

Errors

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {
    "errors": [
      {
        "keyword": "required",
        "params": { "missingProperty": "currency" },
        "message": "must have required property 'currency'",
        "field": "currency"
      }
    ]
  },
  "name": "TNDR004",
  "statusCode": 400
}

Saved cards

Include saved_cards in payment_method_types and the checkout shows the customer's previously saved cards alongside the new card form. Listing, selecting and deleting them is handled for you — there is no extra endpoint to call.

Which customer a saved card belongs to

Saved cards always belong to the customer identified by the session's customer.email. Tonder can configure your account to also require customer.phone for saved cards: the customer is still identified by their email, and the phone is what makes their saved cards available. Ask Tonder support whether your account requires it — it cannot be read from the API.

When your account requires a phone:

• Send both customer.email and customer.phone on every session that includes saved_cards, including the one where the card is first saved (and every card-enrollment session). Without customer.phone there are no saved cards: the customer does not see them.
• The phone does not replace the email. The same phone with a different email is a different customer and does not see those cards.
• Tonder compares the phone exactly as you send it. It is not normalized: +525512345678 and 5512345678 are not the same value. Normalize the number in your own application before you create the session, and always send the same value for the same customer, in E.164 — +, country code and number, for example +525512345678.

"customer": {
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "maria@example.com",
  "phone": "+525512345678"
}

The save-card checkbox

Set payment_method_config.saved_cards.show_save_card_checkbox to true to put a "save this card for future payments" checkbox on the new card form, so the customer can opt in to saving their card.

curl -X POST 'https://api-stage.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_TEST_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
    "amount_total": 150.00,
    "currency": "MXN",
    "line_items": [
      { "name": "Premium Plan", "quantity": 1, "unit_price": 150.00 }
    ],
    "payment_method_types": ["card", "saved_cards"],
    "payment_method_config": {
      "saved_cards": { "show_save_card_checkbox": true }
    },
    "external_id": "ORD-001",
    "return_url": "https://your-store.com/checkout/complete"
  }'

curl -X POST 'https://api.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
    "amount_total": 150.00,
    "currency": "MXN",
    "line_items": [
      { "name": "Premium Plan", "quantity": 1, "unit_price": 150.00 }
    ],
    "payment_method_types": ["card", "saved_cards"],
    "payment_method_config": {
      "saved_cards": { "show_save_card_checkbox": true }
    },
    "external_id": "ORD-001",
    "return_url": "https://your-store.com/checkout/complete"
  }'

Card-on-File

Card-on-File (COF) saves cards automatically and lets the customer pay again without re-entering their CVV. It runs on Tonder's subscription and tokenization infrastructure.

When Card-on-File is enabled for your account, the checkout:

1. Runs a 3D Secure check as the card is saved.
2. Creates a subscription for that card.
3. Accepts payments with it on return visits without asking for the CVV.

If Card-on-File is enabled for your account, the checkout does all of this on its own. The one thing your integration may need to send is customer.phone, when your account also requires a phone for saved cards — see Which customer a saved card belongs to. It is the same subscription the SDK surfaces as subscription_id — see the Web SDK reference.

API reference

curl -X POST "https://example.com/checkout/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "first_name": "Maria",      "last_name": "Garcia",      "email": "maria@example.com"    },    "amount_total": 150,    "currency": "MXN",    "external_id": "ORD-001",    "line_items": [      {        "name": "Premium Plan",        "quantity": 1,        "unit_price": 150,        "product_id": "plan-premium-01"      }    ],    "payment_method_types": [      "card",      "saved_cards",      "oxxopay"    ],    "submit_type": "pay",    "locale": "en",    "return_url": "https://your-store.com/checkout/complete",    "metadata": {      "external_id": "ORD-001"    }  }'

{
  "id": "cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "status": "pending",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_id": 41528,
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "en",
  "amount_total": 150,
  "currency": "MXN",
  "external_id": "ORD-001",
  "return_url": "https://your-store.com/checkout/complete",
  "payment_method_types": [
    "card",
    "saved_cards",
    "oxxopay"
  ],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751483563558,
  "modified_at": 1751483563558,
  "expires_at": 1751569963
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {
    "errors": [
      {
        "keyword": "required",
        "params": {
          "missingProperty": "currency"
        },
        "message": "must have required property 'currency'",
        "field": "currency"
      }
    ]
  },
  "name": "TNDR004",
  "statusCode": 400
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {},
  "name": "TNDR004",
  "statusCode": 400
}

Next steps