Hosted Checkout Guide
The four Hosted Checkout steps, with the request building live.
With Hosted Checkout you create the session and Tonder gives you a URL; you send your customer there to pay, then you check the result. Four steps — and the first one happens once.
🇲🇽 🇨🇱 Mexico and Chile use the same flow. Nothing changes except currency: "MXN" for
Mexico, "CLP" for Chile.
Here you define the logo and colors shown across all your checkout sessions. It isn't repeated per sale: normally you do this once when you integrate.
This endpoint also accepts a logo field to upload the file directly (multipart) instead of a
hosted URL. This guide uses logo_url because it's the common case.
curl -X POST "https://api-stage.tonder.io/checkout/v1/business/config" \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "active",
"logo_url": "https://cdn.my-store.com/logo.png",
"ui_config": {
"branding": {
"brand_color": "#00A859"
},
"theme": {
"shapes": "rounded"
}
}
}'This is the step you repeat on every sale. You tell Tonder who the customer is, what they're buying
and how much they pay. Tonder returns a url: that's where you send your customer to enter payment
details — you never see or touch the card in this flow.
metadata is free-form: send whatever fields help you identify the sale in your own systems. Keep
metadata.external_id — it's the key you'll reconcile the payment by in webhooks.
curl -X POST "https://api-stage.tonder.io/checkout/v1/sessions" \
-H "Authorization: Token YOUR_API_KEY" \
-H "x-idempotency-key: test-001" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"first_name": "Vicente",
"last_name": "Quintero",
"email": "vquintero@testuser.com"
},
"amount_total": 150.00,
"currency": "MXN",
"line_items": [
{
"name": "Deposit",
"quantity": 1,
"unit_price": 150.00,
"product_id": "your internal product id"
}
],
"payment_method_types": [
"card",
"spei",
"oxxopay"
],
"return_url": "https://tonder.io",
"external_id": "ORD-12345-4",
"metadata": {
"external_id": "ORD-12345-4"
}
}'If it succeeds, open the response's url field in a browser: that's where your customer would pay.
Store the session id for step 3.
Your customer can close the window, lose connectivity, or take their time. Instead of relying on
return_url alone, check the session status by its id.
curl -X GET "https://api-stage.tonder.io/checkout/v1/sessions/cs_541_4999601" \
-H "Authorization: Token YOUR_API_KEY"For order fulfillment, base your logic on the transaction status (transaction_status), not on
the session status: completed or expired alone don't confirm whether the payment succeeded or
was declined. See Hosted Checkout reference.
The session tells you whether it was paid; this endpoint gives you the fine detail of the attempt:
which method was used, last 4 digits if it was a card, the brand. Use the payment_id from step 3.
curl -X GET "https://api-stage.tonder.io/checkout/v1/payments/4999601" \
-H "Authorization: Token YOUR_API_KEY"