Idempotency

Use Idempotency-Key to make retry behavior deterministic for write and redeem API requests.

Required Endpoints

Partner API:

• POST /airtime/purchase
• POST /data-packages/purchase
• POST /vouchers/issue

Merchant API:

• POST /merchant-api/vouchers/validate
• POST /merchant-api/claims
• POST /merchant-api/claims/:id/verify

Header Format

Idempotency-Key: 1e7f4c5b-1a68-43f2-87b4-0d7a7d8d8a89

Merchant API validates this header as:

• length 1..255
• allowed characters: letters, digits, -, _, :, .

Retry Rules

• Generate one key per intended operation.
• Reuse the same key only when retrying the same request after timeout or transport failure.
• Keep request method, path, headers used in signing, and body unchanged when retrying.

Idempotent Outcomes

• Replay (completed request): returns the originally stored response for that key.
• Still processing: returns 409 Conflict.
• Payload mismatch with same key: returns 409 Conflict.
• Missing key on required endpoints: returns 400 Bad Request.

Practical Guidance

• Use UUIDs or similarly unique values.
• Store keys with your outbound request logs.
• Keep a retry window long enough to cover network retries and delayed responses.