Authentication
Your API keys, the headers every request needs, and the idempotency key for each integration type.
Tonder authenticates every API request with an API key, sent in the Authorization header.
You get two keys — a public key and a secret key — for different jobs.
Your API keys
- Public key — processes payments, APMs, and Hosted Checkout sessions. Safe to use anywhere your backend can reach Tonder.
- Secret key — for card tokenization (Save Cards). Server-side only — never expose it in client code, mobile apps, or version control.
Get your keys
Find them in the dashboard under Developers → API Keys. Sandbox and production have separate keys:
- Sandbox — dashboard-stage.tonder.io
- Production — dashboard.tonder.io
Never use production keys for testing. See Environments for the full split.
Required headers
Authenticate with the Authorization header plus the JSON content type. The idempotency header
differs by integration type.
The scheme is Token followed by a space, then your key — not Bearer. A missing space
returns 401 Unauthorized.
Hosted Checkout
Authorization: Token YOUR_API_KEY
x-idempotency-key: <free-string>
Content-Type: application/jsonx-idempotency-key is a free string you define (for example test-001), with an idempotency
window of 5 seconds.
API Direct
Authorization: Token YOUR_API_KEY
X-Request-Id: <uuid-v4>
Content-Type: application/jsonX-Request-Id must be a UUID v4 generated per request (not a free string).
| Integration | Idempotency header | Format | Window |
|---|---|---|---|
| Hosted Checkout | x-idempotency-key | free string | 5 seconds |
| API Direct | X-Request-Id | UUID v4 | per request |
Card tokenization
To save cards, exchange your secret key for a short-lived access token: GET /api/v1/tokenization/auth/
returns an access_token (a JWT) used to tokenize card data. The SDKs handle this for you — see
SDKs and API Direct → Authentication.
Webhooks
Always confirm webhooks server-side before acting on them: re-fetch the transaction or session
status (by payment_id / external_id) rather than trusting the received payload alone. See
Webhooks.
Security best practices
- Never expose your secret key in client code, mobile apps, or version control.
- Store credentials in environment variables — don't hardcode them.
- Rotate keys immediately if you suspect they're compromised.
- Use separate keys for sandbox and production.
- Restrict credential access on a need-to-know basis.
Next steps
Environments
Sandbox vs production, base URLs, and going live.
Quickstart
Take your first test payment in four steps.
API Direct
Headers, tokenization, and errors in depth.
Webhooks
Receive and verify payment events.
Tonder Web SDK plugin (AI)
Let Claude Code or Codex integrate the Web SDK for you, backed by versioned docs.