Build

Idempotency

Create requests require the header Idempotency-Key. Use a key from your own system, such as the order id. AFRIPEI will not generate one for you.

The same key and the same body return the original response, including the original payment or payout id. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED. A key that is still running returns 409 IDEMPOTENCY_IN_PROGRESS. Keys are kept for 72 hours.

Retry a timed-out create with the same key. Do not generate a new key until you know the first request never reached the API. A new key can create a second prompt.

Header

Idempotency-Key: order-1001

Webhook deliveries have their own id. Use X-AFRIPEI-Event-ID so a retry does not apply the same payment twice.

What to use as the key

Use a stable id from your system: the order id for a collection, the payroll line for a payout. Do not use a random value generated inside the HTTP client on every attempt. Do not use the clock. The key is how AFRIPEI knows the second call is the same instruction.

The three answers

Same key, same body. You receive the original response and the original id. No second prompt, no second reservation.
Same key, different body. 409 IDEMPOTENCY_KEY_REUSED. Keep the original, or choose a new key only when you mean a new payment.
Same key, still running. 409 IDEMPOTENCY_IN_PROGRESS. Wait, then send that same key again.

The window is 72 hours. After that, the key can be used again as if it were new. Do not reuse an order id for a different amount inside that window.