Quickstart
Take your first test payment with Hosted Checkout in four steps, without building a card form.
Hosted Checkout is the fastest way to get paid: Tonder hosts the payment page, so card data never touches your servers (no PCI scope). This quickstart takes you from zero to a verified test payment in four steps.
Prefer to see it first? The interactive demo shows the Hosted Checkout 2.0 page and builds this request as you change the options.
Before you begin
- A Tonder account — sign in at dashboard.tonder.io (Production) or dashboard-stage.tonder.io (Sandbox).
- Your test API key from Developers → API Keys. Authenticate every request with your
public key:
Authorization: Token YOUR_TEST_API_KEY.
Amounts are in decimal format: 150.00 = MXN 150.00. Set external_id to your order
reference — it's the key you'll reconcile payments by.
Steps
Create a checkout session
From your server, create a session with your public key. The response returns a url to send the
customer to.
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": "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",
"mercadopago",
"oxxopay",
"spei",
"safetypayCash",
"safetypayTransfer",
"neosurf"
],
"return_url": "https://tonder.io",
"external_id": "ORD-12345-4",
"metadata": { "external_id": "ORD-12345-4" }
}'curl -X POST 'https://api.tonder.io/checkout/v1/sessions' \
-H 'Authorization: Token YOUR_LIVE_API_KEY' \
-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",
"mercadopago",
"oxxopay",
"spei",
"safetypayCash",
"safetypayTransfer",
"neosurf"
],
"return_url": "https://tonder.io",
"external_id": "ORD-12345-4",
"metadata": { "external_id": "ORD-12345-4" }
}'The response (200 Created) includes the redirect url, the session id, and a pending status:
{
"id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980b",
"url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980b",
"status": "pending",
"payment_id": 41521,
"amount_total": 150.00,
"currency": "MXN",
"external_id": "ORD-12345-4",
"transaction_status": "Pending"
}Redirect the customer
Send the customer to the url from the response — that's Tonder's hosted payment page.
res.redirect(session.url);Complete a test payment
On the hosted page, pay with a test card: 4000 0000 0000 0077 (approved), any future expiry
(e.g. 12/30), and any 3-digit CVC (e.g. 123). Find the full set of test cards under
Developers → Test Data in the dashboard.
When done, Tonder returns the customer to your return_url with the session id appended:
https://your-store.com/checkout/complete?session_id=cs_97_41521_….
Confirm the result
Always confirm server-side — don't assume the redirect means success.
- Webhook (recommended). Tonder sends a
payment_Successevent to your endpoint (Developers → Webhooks). Match it to your order viametadata.external_idand respond200. - Status check. Or fetch the session and read
status:
curl -X GET 'https://api-stage.tonder.io/checkout/v1/sessions/cs_97_41521_d11ba771527b4056c7f85786cfbb980b' \
-H 'Authorization: Token YOUR_TEST_API_KEY'curl -X GET 'https://api.tonder.io/checkout/v1/sessions/cs_97_41521_d11ba771527b4056c7f85786cfbb980b' \
-H 'Authorization: Token YOUR_LIVE_API_KEY'A successful payment returns status: "completed" and transaction_status: "Success":
{
"id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980b",
"status": "completed",
"transaction_status": "Success",
"amount_total": 150.00,
"currency": "MXN",
"external_id": "ORD-12345-4",
"paid_at": 1751478550234
}Webhooks are the most reliable way to confirm payments — prefer them over polling. Acknowledge
each event with a 200 and reconcile using metadata.external_id.