Developer guide

Idempotency

Safely retry POSTs with an Idempotency-Key header.

POST endpoints support an Idempotency-Key header; payout sends and withdrawal creation 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.

Withdrawals require a stable key of 1–200 characters and the exact same body on retries. Their creation response and ledger entries commit together; the receipt does not expire. Keys are isolated by authenticated merchant, shop and environment. A changed committed body returns 409. After a timeout, call GET /api/v1/withdrawals with the original Idempotency-Key to recover the request. A 404 can mean the first request is still running: retain the original key and body. Never create another key to resolve uncertainty.

bash

curl https://api.testing.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.