API Documentation

RapidBills API Reseller Docs

Base URL: https://www.rapidbills.ng/api/reseller/v1

Auth Header: Authorization: Bearer YOUR_API_KEY

Alternative Header: X-API-Key: YOUR_API_KEY

Common Response Shape

Idempotency: send a unique Idempotency-Key header on every POST purchase/reset call.

If the same key is retried with the same payload, the API replays the original response. If payload changes, API returns 409.

{
  "status": "true|false",
  "message": "Human readable message",
  "data": {}
}

Idempotency-Key Guide

Idempotency-Key prevents duplicate charges when clients retry due to timeout/network errors.

• Generate one key per logical action (for example one purchase click).
• Reuse the same key only when retrying that exact same request.
• If payload changes, generate a new key.
• UUID v4 is recommended.

JavaScript (Node/Browser)

const idemKey = crypto.randomUUID();

Python

import uuid
idem_key = str(uuid.uuid4())

PHP

$idemKey = bin2hex(random_bytes(16));

Use in Header

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

1) Get User Balance

GET https://www.rapidbills.ng/api/reseller/v1/user-balance/

Expected Success Response

{
  "status": "true",
  "message": "Balance fetched successfully.",
  "data": {
    "main_balance": "4500.00",
    "cashback_balance": "120.00",
    "funding_accounts": [
      {
        "provider": "Paystack",
        "provider_code": "paystack",
        "account_name": "John Doe",
        "account_number": "1234567890",
        "bank_name": "Wema Bank",
        "is_primary": true,
        "active": true
      }
    ]
  }
}

JavaScript

const axios = require("axios");
const API_KEY = "YOUR_API_KEY";
const BASE = "https://www.rapidbills.ng/api/reseller/v1";

const res = await axios.get(`${BASE}/user-balance/`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
console.log(res.data);

Python

import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://www.rapidbills.ng/api/reseller/v1"

res = requests.get(
    f"{BASE}/user-balance/",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)
print(res.json())

PHP

<?php
$apiKey = "YOUR_API_KEY";
$base = "https://www.rapidbills.ng/api/reseller/v1";

$ch = curl_init("$base/user-balance/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $apiKey"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

cURL

curl --request GET "https://www.rapidbills.ng/api/reseller/v1/user-balance/" \
  --header "Authorization: Bearer YOUR_API_KEY"

2) Buy Data

POST https://www.rapidbills.ng/api/reseller/v1/buy-data/

Request Body

{
  "bundle_id": 1,
  "number": "08012345678",
  "wallet": "main"
}

Expected Success Response

{
  "status": "true",
  "message": "Data purchase successful.",
  "tx_ref": "AbCdEfGhIj"
}

JavaScript

await axios.post(`${BASE}/buy-data/`, {
  bundle_id: 1,
  number: "08012345678",
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/buy-data/", json={
    "bundle_id": 1,
    "number": "08012345678",
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "bundle_id" => 1,
  "number" => "08012345678",
  "wallet" => "main"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-data/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"bundle_id":1,"number":"08012345678","wallet":"main"}'

3) Buy Airtime

POST https://www.rapidbills.ng/api/reseller/v1/buy-airtime/

Request Body

{
  "provider_id": 1,
  "number": "08012345678",
  "amount": 1000,
  "wallet": "main"
}

Expected Success Response

{
  "status": "true",
  "message": "Airtime purchase successful.",
  "tx_ref": "AbCdEfGhIj"
}

JavaScript

await axios.post(`${BASE}/buy-airtime/`, {
  provider_id: 1,
  number: "08012345678",
  amount: 1000,
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/buy-airtime/", json={
    "provider_id": 1,
    "number": "08012345678",
    "amount": 1000,
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "provider_id" => 1,
  "number" => "08012345678",
  "amount" => 1000,
  "wallet" => "main"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-airtime/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"provider_id":1,"number":"08012345678","amount":1000,"wallet":"main"}'

4) Buy Electricity

POST https://www.rapidbills.ng/api/reseller/v1/buy-power/

Request Body

{
  "provider_id": 1,
  "meter_number": "12345678901",
  "meter_type": 1,
  "amount": 2000,
  "phone_number": "08012345678",
  "wallet": "main"
}

Expected Success Response

{
  "status": "true",
  "message": "Electricity purchase successful.",
  "tx_ref": "AbCdEfGhIj",
  "token": "1234 5678 9012"
}

JavaScript

await axios.post(`${BASE}/buy-power/`, {
  provider_id: 1,
  meter_number: "12345678901",
  meter_type: 1,
  amount: 2000,
  phone_number: "08012345678",
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/buy-power/", json={
    "provider_id": 1,
    "meter_number": "12345678901",
    "meter_type": 1,
    "amount": 2000,
    "phone_number": "08012345678",
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "provider_id" => 1,
  "meter_number" => "12345678901",
  "meter_type" => 1,
  "amount" => 2000,
  "phone_number" => "08012345678",
  "wallet" => "main"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-power/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"provider_id":1,"meter_number":"12345678901","meter_type":1,"amount":2000,"phone_number":"08012345678","wallet":"main"}'

5) Buy Cable

POST https://www.rapidbills.ng/api/reseller/v1/buy-cable/

Request Body

{
  "plan_id": 1,
  "card_number": "12345678901",
  "wallet": "main"
}

Expected Success Response

{
  "status": "true",
  "message": "Cable purchase successful.",
  "tx_ref": "AbCdEfGhIj"
}

JavaScript

await axios.post(`${BASE}/buy-cable/`, {
  plan_id: 1,
  card_number: "12345678901",
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/buy-cable/", json={
    "plan_id": 1,
    "card_number": "12345678901",
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "plan_id" => 1,
  "card_number" => "12345678901",
  "wallet" => "main"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-cable/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"plan_id":1,"card_number":"12345678901","wallet":"main"}'

6) Buy Exam Pin

POST https://www.rapidbills.ng/api/reseller/v1/buy-exam/

Request Body

{
  "exam_id": 1,
  "wallet": "main"
}

Expected Success Response

{
  "status": "true",
  "message": "Exam purchase successful.",
  "tx_ref": "AbCdEfGhIj",
  "pins": ["123456789012"]
}

JavaScript

await axios.post(`${BASE}/buy-exam/`, {
  exam_id: 1,
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/buy-exam/", json={
    "exam_id": 1,
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "exam_id" => 1,
  "wallet" => "main"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-exam/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"exam_id":1,"wallet":"main"}'

7) Utility Endpoints

• GET https://www.rapidbills.ng/api/reseller/v1/catalog/ - provider IDs, bundles, cable plans, exams.
• GET https://www.rapidbills.ng/api/reseller/v1/pricing/ - tier-specific product pricing table.
• GET https://www.rapidbills.ng/api/reseller/v1/user-balance/ - main balance, cashback, and funding account numbers.
• GET https://www.rapidbills.ng/api/reseller/v1/profile/ - current API profile + key prefix metadata.
• POST https://www.rapidbills.ng/api/reseller/v1/reset-key/ - rotate API key and return new key once.

8) Buy Gift Card

POST https://www.rapidbills.ng/api/reseller/v1/buy-gift-card/

Request Body

{
  "amount": 1000,
  "wallet": "main"
}

Expected Success Response

{
  "status": "true",
  "message": "Gift card purchased successfully.",
  "data": {
    "code": "AB12CD34EF",
    "amount": "1000.00",
    "status": "valid",
    "expires_at": "2027-03-01T12:00:00Z"
  }
}

JavaScript

await axios.post(`${BASE}/buy-gift-card/`, {
  amount: 1000,
  wallet: "main"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/buy-gift-card/", json={
    "amount": 1000,
    "wallet": "main",
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "amount" => 1000,
  "wallet" => "main"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/buy-gift-card/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"amount":1000,"wallet":"main"}'

9) Redeem Gift Card

POST https://www.rapidbills.ng/api/reseller/v1/redeem-gift-card/

Request Body

{
  "code": "AB12CD34EF"
}

Expected Success Response

{
  "status": "true",
  "message": "Gift card redeemed successfully.",
  "data": {
    "code": "AB12CD34EF",
    "amount": "1000.00",
    "status": "used"
  }
}

JavaScript

await axios.post(`${BASE}/redeem-gift-card/`, {
  code: "AB12CD34EF"
}, { headers: { Authorization: `Bearer ${API_KEY}` } });

Python

requests.post(f"{BASE}/redeem-gift-card/", json={
    "code": "AB12CD34EF"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)

PHP

$payload = json_encode([
  "code" => "AB12CD34EF"
]);

cURL

curl --request POST "https://www.rapidbills.ng/api/reseller/v1/redeem-gift-card/" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"code":"AB12CD34EF"}'