Idempotency

Safely replay creation requests using idempotency keys to avoid double payments and transfers.

Network outages happen. If you don't know whether a creation request succeeded, replaying it without precaution could charge or pay out twice. Idempotency keys eliminate this risk.

Two pages on idempotency

This page covers the technical mechanics of the Idempotency-Key header: the header format, conflict behavior, scope, and retention window. For concrete implementation strategies — how to generate keys, how to handle retries, and how to deduplicate webhooks — see Best Practices → Idempotency.

How it works

Add a unique Idempotency-Key header (no X- prefix) to a POST /payments or POST /transfers request. Wajub associates the result with that key for 24 hours: replaying the same key returns the original response without recreating the resource.

Idempotent creation

curl https://api.wajub.com/transfers \
-H "Authorization: sk.xxxx" \
-H "Idempotency-Key: idmp_3pQ9aZ7Zk1" \
-H "Content-Type: application/json" \
-d '{ "amount": 100000, "beneficiary": {"phone": "237670000000", "channel": "cm.mtn", "name": "Amina"} }'

Rules

Idempotency-Keystringoptional

Unique identifier generated by you (UUID v4 recommended). 1–128 characters, matching `[A-Za-z0-9._:-]+`.

Scopestringoptional

Supported on `POST /payments` and `POST /transfers` only. Keyed by (idempotency key, team, sandbox/live) — a key used in sandbox is independent from the same key used live.

Window24 hoptional

After that, the key is forgotten and the request will be treated as new.

Conflict422optional

Reusing an Idempotency-Key with a different request body returns a 422 validation error on the `idempotency_key` field, currently enforced on `POST /payments` (not yet on `POST /transfers`).

Not X-Idempotency-Key

The header is Idempotency-Key, with no X- prefix. (X-Idempotency-Key is a different, internal header used only for inbound provider-webhook ingestion — it has nothing to do with the merchant-facing API.)

One key per business intent

Generate the key at the moment of intent (e.g. on the "Pay" click), not on each network attempt. This way all retries of the same action share the key and remain idempotent.

Verify replays

In Konsole → API Logs, responses served from the idempotency cache are marked with a replayed badge.

Rate LimitsQuotas and headers.VersioningVersioned API releases.