Developer guide

Idempotency

Safely retry POSTs with an Idempotency-Key header.

POST endpoints support an Idempotency-Key header; payout sends require it. Reusing the same key replays the original response without duplicating work — safe to retry network failures.

This covers every money-moving endpoint: creating a payment (/payments), requesting a withdrawal (/withdrawals) and issuing a refund (/payments/{id}/refund). A retried request never opens a second withdrawal or refund.

bash

curl https://sandbox.key2pay.ai/api/v1/payments \
  -H "Key2Pay-Version: 2026-10-12" \
  -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`. Recover the original operation before starting another payment.
No key + retry	A payout send rejects a missing key before debit. Endpoints where the key is optional can create another operation when retried without it.
TTL	General response cache: 24 hours. Payout send keys are permanent for committed operations; never reuse a payout key for a new transfer.

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.