Idempotency

Why it matters

A network timeout doesn't tell you whether your request succeeded before the connection dropped. If that request was "withdraw £500," retrying it blind can pay a customer twice. The Idempotency-Key header exists so a retry is provably safe.

How to use it

Send a unique value in Idempotency-Key on every POST, PATCH, or DELETE request:

curl -X POST https://api.kwiikpay.io/api/v1/partner/customers/{customerId}/banking/withdrawals \
  -H "X-Api-Key: kwp_live_..." \
  -H "Idempotency-Key: withdrawal-2026-08-09-a1b2c3" \
  -H "Content-Type: application/json" \
  -d '{ "...": "..." }'

The header is required on every mutating call — a request without one is rejected before it reaches any business logic.

What happens on retry

• Same key, same request body → you get back the original result. No duplicate is created.
• Same key, different request body → rejected. Reusing a key for a different action is a bug in the caller, not a retry, and the API won't guess which one you meant.
• A new action needs a new key. A good pattern is to derive the key from something inherent to the action itself (an internal transaction ID you generated, a UUID minted once per user click) — not a timestamp or random value regenerated on every attempt, which would defeat the point.

Key format

8–256 visible ASCII characters. Any string that uniquely identifies the action on your side works — a UUID is the simplest reliable choice.