Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tonder.io/llms.txt

Use this file to discover all available pages before exploring further.

When creating a Hosted Checkout session via POST /checkout/v1/sessions, you can include the x-idempotency-key header to prevent duplicate charges in case of network errors or client retries.
x-idempotency-key is optional but recommended for any integration that retries session creation requests.

​
How It Works

If the server receives two requests with the same x-idempotency-key within the protection window, it treats the second as a retry and returns the original session without creating a new charge. After the window expires, a new request with the same key creates a new session.
ScenarioResult
Same key, within 5 secondsReturns the same session — no duplicate created
Same key, after 5 secondsCreates a new session
Different keyAlways creates a new session

​
Implementation

​
Header Configuration

Add x-idempotency-key alongside your other headers when calling the session endpoint:
HeaderValueRequiredDescription
AuthorizationToken <API_PUBLIC_KEY>YesYour Public API Key from the Tonder Dashboard
Content-Typeapplication/jsonYesRequired for JSON body
x-idempotency-key<unique_id>NoUnique key to guarantee idempotency. Default protection window: 5 seconds
You can find your Public API Key in your Tonder Dashboard.

​
Generating a Key

Use a combination of your internal order identifier and a timestamp to create a key that is unique per session attempt and human-readable in logs: 
x-idempotency-key: {external_id}-{timestamp}
Example: 
x-idempotency-key: ORD-2025-A9B8-1739876543

​
Full Request Example

curl -X POST 'https://api-stage.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: ORD-2025-A9B8-1739876543' \
  -d '{
    "customer": {
      "first_name": "Juan",
      "last_name": "Perez",
      "email": "juan.perez@example.com"
    },
    "amount_total": 25000,
    "currency": "MXN",
    "line_items": [
      {
        "name": "Blue T-Shirt",
        "quantity": 1,
        "unit_price": 25000
      }
    ],
    "return_url": "https://your-store.com/checkout/complete",
    "external_id": "ORD-2025-A9B8"
  }'

​
When to Reuse vs. Regenerate a Key

Reuse the same key only when retrying the exact same session creation request after a network error or timeout. Generate a new key whenever the request body changes — for example, if the customer updates their cart or switches currency before retrying.
Generating a new key on each retry defeats idempotency protection. Store the key alongside your order record before sending the first request so you can retrieve it on retry.

​
Next Steps