Skip to main content

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 same idempotency_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.
Use a UUID or your internal order ID as the key. It must be unique per purchase attempt. A good format: {your_prefix}_{order_id}_{timestamp}

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 retry
  • pending → wait and requery again
  • failed → wallet refunded, safe to retry /purchase with a new idempotency_key