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 /api/v1/merchant/client/topup-transactions/initiate-claim
• POST /api/v1/merchant/client/topup-transactions/redeem-gift
• POST /api/v1/merchant/redeem-gift/callback

Header Format

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

Partner APIs validate this header as:

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

Merchant-redeem uses body idempotency fields instead:

• idempotencyKey on initiate-claim and redeem-gift
• callbackId on redeem-gift/callback

Retry Rules

• Generate one key per intended operation.
• Use separate keys for claim initiation, gift redemption, and callback completion.
• 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 header key on required partner 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.