Core
Idempotency
Safely retry POSTs with an Idempotency-Key header.
POST endpoints accept an optional Idempotency-Key header. Reusing the same key replays the original response without duplicating work — safe to retry network failures.
bash
curl https://sandbox.key2pays.com/api/v1/payments \
-H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
-H "Idempotency-Key: 7c1fd0d4-5e94-4b3e-a8b6-8c4f2a9e1c2d" \
-H "Content-Type: application/json" \
-d '{ "amount": 45, "paymentMethodId": "1001", "country": "MEX" }'Semantics
| Case | Behaviour |
|---|---|
| Same key, same body | Returns the original response from cache. Response includes Idempotent-Replayed: true header. No new charge. |
| Same key, different body | Returns 409 Conflict with code idempotency_conflict. Pick a new key. |
| No key + retry | No deduplication. Will create a second charge — your duty to add the header on every retryable call. |
| TTL | 24 hours from first use. After expiry the same key is fair game again. |
Keys are scoped per (apiKey + endpoint). Use a v4 UUID — any string up to 255 chars is accepted but UUIDs guarantee no accidental collisions across retries.