Idempotency & retries
Retry safely — never risk a duplicate charge.
Network calls fail, clients time out, users double-click a submit button. Send an
Idempotency-Key header on POST /v1/payments and a retried request with the same
key always returns the same payment — never a duplicate — even if your original
request's response never made it back to you.
curl -X POST https://connect.tchokopay.com/v1/payments \
-H "Authorization: Bearer tchoko_live_..." \
-H "Idempotency-Key: order-4821-attempt-1" \
-H "Content-Type: application/json" \
-d '{ "amount": 5000, "currency": "XAF", "reference": "order_4821" }'Choosing a key
Use a fresh, unique key per distinct payment attempt — your own order ID, or a UUID you generate client-side, both work well.
- Reusing a key on purpose is exactly how you get safe retries: same key, same in-flight or completed payment, every time.
- Reusing a key across genuinely different payments doesn't create a second payment — it just hands you back the first one. If that's not what you want, generate a new key.
Max length
Idempotency-Key is capped at 200 characters — anything longer is rejected with a
400 before it touches anything.
What counts as "the same request"
The key alone determines the match — it's scoped to your account, so two different merchants can safely use the same key value without colliding. Concurrent requests with the same key are handled safely too: if two requests race, exactly one creates the payment and the other gets back that same result, never a duplicate and never an error.