What is Idempotency?
An idempotent request is one that can be safely retried without causing duplicate side effects. If you send two purchase requests with the sameidempotency_key, only one transaction is created — the second request simply returns the original.
This protects your users from being double-charged when your network drops mid-request.
How to Use It
You can pass an idempotency key either in the request body ("idempotency_key": "...") or as an HTTP header (Idempotency-Key: ...). Both Live Mode and Sandbox (Test) Mode support idempotency key verification.
Duplicate Detection Response
When the same key is submitted again:Correct Flow for Timeouts
1
Send the purchase request
Include a unique
idempotency_key.2
Network timeout occurs
You don’t receive a response. Do not retry
/purchase yet.3
Wait 30 seconds
Give the provider time to complete processing.
4
Call POST /requery
Use the transaction
reference to check if the purchase went through.5
Act on the status
success→ transaction completed, do not retrypending→ wait and requery againfailed→ wallet refunded, safe to retry/purchasewith a newidempotency_key

