Integration guides
Idempotency
Retry safely without creating duplicate payments, numbers or payouts.
Every request that creates something takes an idempotency key. If you send the same key again, TeePay returns the original result instead of doing the work twice.
| Endpoint | Where the key goes |
|---|---|
POST /v1/collections | Idempotency-Key header |
POST /v1/checkout-sessions | Idempotency-Key header (8 to 120 characters) |
POST /v1/control-numbers | Idempotency-Key header |
POST /v1/disbursements | idempotency_key in the body |
Keys are 8 to 128 characters of letters, digits, _ and -.
Rules
- Derive the key from your own record, for example
order-1001orpayout-2026-10-0001. Do not generate a new random key on each retry. - Same key, same body: you get the original result. Checkout sessions add
Idempotent-Replayed: true. - Same key, different body:
409 idempotency_conflict. Nothing is created. - Uncertain outcomes: if a request times out or returns
202, retry with the same key or read the resource. A new key can create a second payment or payout. - A new attempt after a final failure (for example the customer cancelled the prompt) needs a new key, such as
order-1001-2.