> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rapidtopup.com.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Prevent duplicate charges on network timeouts by using idempotency keys.

## 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.

```json theme={null}
{
  "type": "data",
  "service_id": "mtn-data",
  "phone_number": "08012345678",
  "variation_code": "mtn-1gb",
  "reference": "MY_ORDER_123",
  "idempotency_key": "order_abc123_1727942400"
}
```

> [!TIP]
>
> 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:

```json theme={null}
{
  "message": "Duplicate request detected. Returning original transaction.",
  "transaction": {
    "reference": "RTU-DATA-20261003-AB12CD",
    "status": "success",
    ...
  },
  "is_duplicate": true
}
```

***

## 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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.