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

# Make a Purchase

> The core endpoint. Supports Airtime, Data, Cable TV, and Electricity purchases.

## Request

**Authorization** `string` *required*

Your API secret key. Format: `Bearer <api-key>`

**Content-Type** `string` *required*

Must be `application/json`

**type** `string` *required*

Transaction type. One of: `airtime`, `data`, `cable_tv`, `electricity`

**service\_id** `string` *required*

Network or provider ID from the `/services/*` endpoints.

* **Airtime:** `mtn`, `airtel`, `glo`, `9mobile`
* **Data:** `mtn-data`, `airtel-data`, `glo-data`, `9mobile-data`
* **Cable TV:** `dstv`, `gotv`, `startimes`
* **Electricity:** `ikeja-electric`, `eko-electric`, `ibadan-electric`, etc.

**phone\_number** `string` *required*

* **Airtime/Data:** 11-digit Nigerian phone number (e.g. `08012345678`)
* **Cable TV:** 10-digit smartcard number
* **Electricity:** Meter number

**amount** `number`

Amount in NGN. **Required for airtime only.** Minimum: `50`

**network** `string`

Network name. **Required for airtime/data.** E.g. `mtn`, `airtel`, `glo`, `9mobile`

**variation\_code** `string`

Plan or meter type code. **Required for data, cable TV, and electricity.**
Get valid codes from the `/services/*` endpoints (e.g. `rapid_data_001`, `rapid_cable_001`). For electricity: `prepaid` or `postpaid`.

**reference** `string` *required*

A unique merchant transaction reference string (UUID or timestamped code) to prevent duplicate charges.

**idempotency\_key** `string`

An optional unique idempotency key to prevent double-charging on network retries. Can also be passed via the `Idempotency-Key` HTTP header. Supported in both Live and Sandbox modes.

***

## Examples

```bash cURL — Data theme={null}
curl --request POST \
  --url https://api.rapidtopup.com.ng/api/v2/b2b/purchase \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "data",
    "service_id": "mtn-data",
    "network": "mtn",
    "variation_code": "rapid_data_001",
    "phone_number": "08012345678",
    "reference": "YOUR_UNIQUE_REF_001"
  }'
```

```bash cURL — Airtime theme={null}
curl --request POST \
  --url https://api.rapidtopup.com.ng/api/v2/b2b/purchase \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "airtime",
    "service_id": "airtel",
    "network": "airtel",
    "phone_number": "09012345678",
    "amount": 500,
    "reference": "YOUR_UNIQUE_REF_002"
  }'
```

```bash cURL — Cable TV theme={null}
curl --request POST \
  --url https://api.rapidtopup.com.ng/api/v2/b2b/purchase \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "cable_tv",
    "service_id": "dstv",
    "variation_code": "rapid_cable_001",
    "phone_number": "1234567890",
    "reference": "YOUR_UNIQUE_REF_003"
  }'
```

```bash cURL — Electricity theme={null}
curl --request POST \
  --url https://api.rapidtopup.com.ng/api/v2/b2b/purchase \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "electricity",
    "service_id": "ikeja-electric",
    "variation_code": "prepaid",
    "phone_number": "04012345678",
    "amount": 5000,
    "reference": "YOUR_UNIQUE_REF_004"
  }'
```

```javascript JavaScript (Fetch) theme={null}
// Data purchase example — adapt body for other service types
const response = await fetch('https://api.rapidtopup.com.ng/api/v2/b2b/purchase', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'data',
    service_id: 'mtn-data',
    network: 'mtn',
    variation_code: 'rapid_data_001',
    phone_number: '08012345678',
    reference: 'YOUR_UNIQUE_REF_001',
  }),
});

const data = await response.json();
console.log(data.data.reference); // "RTU-DATA-20261003-AB12CD"
console.log(data.data.status);    // "success"
```

```php PHP (Guzzle) theme={null}
<?php

use GuzzleHttp\Client;

$client = new Client();

// Data purchase example — adapt body for other service types
$response = $client->request('POST', 'https://api.rapidtopup.com.ng/api/v2/b2b/purchase', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer <api-key>',
        'Content-Type'  => 'application/json',
    ],
    'json' => [
        'type'           => 'data',
        'service_id'     => 'mtn-data',
        'network'        => 'mtn',
        'variation_code' => 'rapid_data_001',
        'phone_number'   => '08012345678',
        'reference'      => 'YOUR_UNIQUE_REF_001',
    ],
]);

$data = json_decode($response->getBody(), true);
echo $data['data']['reference']; // "RTU-DATA-20261003-AB12CD"
echo $data['data']['status'];    // "success"
```

***

## Responses

> [!NOTE]
>
> A `200 OK` HTTP status means we successfully received and processed your request — **not** that the top-up was delivered. Always check the `data.status` field inside the JSON response body: it can be `success`, `pending`, or `failed`. A `pending` status means the upstream carrier is still processing — use `POST /requery` to check for the final outcome.

**status** `string`

`success` or `error`

**data** `object`

**data fields**

**reference** `string`

RapidTopup's internal system tracking reference. E.g. `RTU-DATA-20261003-AB12CD`.

**requestId** `string`

Echoes back your merchant reference ID sent in the request body for server-side reconciliation.

**type** `string`

The transaction type: `airtime`, `data`, `cable_tv`, or `electricity`

**service\_id** `string`

The provider used for this transaction.

**phone\_number** `string`

The phone/meter/smartcard number the transaction was sent to.

**amount** `string`

Amount deducted from your wallet in NGN.

**status** `string`

`success`, `pending`, or `failed`

**token** `string | null`

**Electricity purchases only.** The 20-digit token the customer physically types into their prepaid meter to load the credit. **Display this prominently to your user immediately after a successful purchase.** `null` for all other service types.

**units** `string | null`

**Electricity purchases only.** The energy units (kWh) purchased. E.g. `"13.3"` means 13.3 kWh loaded onto the meter. Display alongside the token on your receipt screen. `null` for all other service types.

**receipt\_number** `string | null`

Official transaction receipt number if applicable. `null` for all other types.

**created\_at** `string`

ISO 8601 timestamp in UTC.

**✅ Success `200`:**

```json theme={null}
{
  "status": "success",
  "environment": "sandbox",
  "message": "Transaction successful",
  "data": {
    "reference": "RTU-DATA-20261003-AB12CD",
    "requestId": "YOUR_UNIQUE_REF_001",
    "type": "data",
    "service_id": "mtn-data",
    "phone_number": "08012345678",
    "amount": "400.00",
    "status": "success",
    "token": null,
    "created_at": "2026-10-03T08:00:00.000000Z"
  }
}
```

**❌ Insufficient Balance `422`:**

```json theme={null}
{
  "status": "error",
  "message": "Insufficient wallet balance. Please top up your account."
}
```

> [!WARNING]
>
> For Cable TV and Electricity purchases, you **must** call `GET /services/verify` first to validate the account and display the customer name to your user. Skipping this step can result in irreversible charges to the wrong account.


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