Quickstart

Hosted Checkout is the fastest way to get paid: Tonder hosts the payment page, so you never touch card data. This quickstart takes you from zero to a verified test payment in four steps.

What you'll build: a server that creates a payment session, redirects the customer to Tonder, and confirms the final status after they return.

Before you begin

• A Tonder account — sign in at dashboard-stage.tonder.io (Sandbox).
• Your test API key from Developers → API Keys.

Integration flow

The diagram shows the full exchange between your customer, your application, and Tonder. Each step below maps to the diagram.

Step 1: Create a payment session

From your server, call the create-session endpoint. It registers the payment with Tonder and returns a secure URL to redirect the customer to, plus the payment_id of the payment it created.

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": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com"
    },
    "amount_total": 150.00,
    "currency": "MXN",
    "line_items": [
      { "name": "Test Product", "quantity": 1, "unit_price": 150.00, "product_id": "your internal product id" }
    ],
    "submit_type": "pay",
    "locale": "en",
    "return_url": "https://your-store.com/checkout/complete",
    "external_id": "ORD-001",
    "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' \
  -d '{
    "customer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com"
    },
    "amount_total": 150.00,
    "currency": "MXN",
    "line_items": [
      { "name": "Test Product", "quantity": 1, "unit_price": 150.00, "product_id": "your internal product id" }
    ],
    "submit_type": "pay",
    "locale": "en",
    "return_url": "https://your-store.com/checkout/complete",
    "external_id": "ORD-001",
    "metadata": { "external_id": "ORD-001" }
  }'

Tonder responds with a session object. Keep the id (to verify later), the url (to redirect to) and the payment_id (your reference for this payment in reconciliation and support):

{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "pending",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_id": 41521,
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "en",
  "amount_total": 150.00,
  "currency": "MXN",
  "external_id": "ORD-001",
  "created_at": 1751478543567,
  "expires_at": 1751564943
}

Step 2: Redirect the customer to Tonder

Send the customer to the url from the response — typically an HTTP 302 redirect:

res.redirect(data.url);

Step 3: Complete the test payment

On Tonder's hosted page the customer enters their details. Tonder handles verification with the acquiring bank and 3DS automatically; if a payment is declined, the customer can retry with a different card on the same page. To complete a test payment:

After submitting, Tonder processes the payment, verifies it with the provider, and redirects the customer to your return_url (or success_url).

Step 4: Verify the payment status

When the customer lands back on your return_url, the URL includes the session ID:

https://your-store.com/checkout/success?session_id=cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d

Use that session_id to call Get a Session from your server. This is more reliable than assuming the redirect means success:

curl -X GET 'https://api-stage.tonder.io/checkout/v1/sessions/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d' \
  -H 'Authorization: Token YOUR_TEST_API_KEY'

curl -X GET 'https://api.tonder.io/checkout/v1/sessions/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d' \
  -H 'Authorization: Token YOUR_API_KEY'

A completed payment returns status: "completed" with the payment_id:

{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "completed",
  "payment_id": 41521,
  "amount_total": 150.00,
  "currency": "MXN",
  "external_id": "ORD-001",
  "transaction_status": "Success",
  "paid_at": 1751478550234
}

Base fulfillment on transaction_status, the result of the customer's latest attempt. A customer can retry in the same session, so a first Declined can become Success.

Next steps