Legacy Hosted Checkout
What the first-generation checkout and the legacy payment flow are, how to stay on them, and how to move to 2.0.
This page describes the first-generation Hosted Checkout. New integrations should follow Hosted Checkout 2.0.
"Legacy" covers two independent things. Your integration may use one, both or neither.
| Legacy | Hosted Checkout 2.0 | |
|---|---|---|
| Checkout design | v1 — the first-generation page | v2 — order summary, templates, fonts, es / en / zh, Apple Pay |
| Payment flow | Legacy processing, with the legacy webhook payloads | Direct API processing, with the standard Tonder webhooks |
The endpoints are the same on both: POST /checkout/v1/sessions, GET /checkout/v1/sessions/{id},
GET /checkout/v1/payments/{payment_id} and /checkout/v1/business/config. A session never
switches design or flow mid-way: both are fixed when it is created.
The v1 design
New payment sessions use the v2 design unless you ask otherwise. To keep the first-generation
design:
- For your whole business — save
checkout_ui_version=v1as a business default with Save business configuration. - For one session — send
"checkout_ui_version": "v1"when you create it.
{
"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"],
"checkout_ui_version": "v1",
"external_id": "ORD-001",
"return_url": "https://your-store.com/checkout/complete"
}What the v1 design does not have: templates, the font selector, the order-summary layout and
Apple Pay. Enrollment sessions always use v1.
The legacy payment flow
How your payments are processed is set per account, not per request. You integrate the same way in both cases; what changes is what you get back:
| Legacy flow | Direct API flow | |
|---|---|---|
payment_id | Returned at creation | Returned at creation |
payment_flow | Not present | direct |
direct_transaction_id | Not present | Present once the customer has tried to pay |
transaction_status before the first attempt | Pending or "" | "" |
| Webhooks | Legacy payloads | Standard Tonder webhooks |
| Apple Pay | Not available | Available on the v2 design |
When your account moves to the Direct API, new sessions stop producing legacy webhook payloads. Update your webhook handler to the standard format before the move. If you are not sure which flow your account uses, check with Tonder support.
Moving to 2.0
Send "checkout_ui_version": "v2" on a Sandbox session, or use the
interactive demo. Nothing else in your request changes.
Handle the standard payment webhooks (event_type: payment_Pending, payment_Success,
payment_Failed) alongside the legacy ones. See
Listen for webhooks.
session.created, session.completed and session.expired are no longer sent on any flow.
Follow the session with payment webhooks or Get a session.
GET /checkout/v1/payments/{payment_id} accepts only the numeric payment_id.
Once your handler is ready, Tonder support switches your account to
the Direct API. Remove the v1 default when you want the new design everywhere.