NEW APP AVAILABLE FOR DOWNLOAD NOW

Get it on Google PlayDownload on the App Store
RizPay|RizPay Developer API
Get API Keys

Quick Start

Make your first API call in 5 minutes

Get up and running with the RizPay API in 5 minutes.

Prerequisites

  • A RizPay business account
  • API access enabled in your settings
  • Your API key from Settings > API Keys

Using Postman? Download our Postman Collection to get started quickly with pre-configured requests.

Step 1: Get Your API Key

  1. Log in at my.rizpay.app
  2. Go to Settings > API Keys
  3. Click Create New Key
  4. Select scopes and environment
  5. Copy your secret key (shown only once!)

Your key looks like: sk_live_xxxxxxxxxxxx (production) or sk_test_xxxxxxxxxxxx (sandbox)

Warning: Never share your secret key or commit it to version control.

Step 2: Check Your Balance

Verify your API key works:

bash
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  https://my.rizpay.app/api/partners/v1/account/balance

Response:

json
{
  "status": { "code": 200, "message": "Balance retrieved" },
  "data": {
    "balance": "50000.00",
    "currency": "NGN",
    "updated_at": "2026-05-18T10:30:00+01:00"
  }
}

Step 3: List Products

See available airtime products:

bash
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  "https://my.rizpay.app/api/partners/v1/products/airtimes?network=MTN"

Response:

json
{
  "status": { "code": 200, "message": "Airtime products retrieved" },
  "data": [
    {
      "id": "prd_42",
      "type": "airtime",
      "attributes": {
        "display_name": "MTN Airtime",
        "network": "MTN",
        "min_amount": "50.0",
        "max_amount": "50000.0",
        "price": {
          "currency": "NGN",
          "basis": "face_value",
          "min_amount": "50.00",
          "max_amount": "50000.00"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

Product ids are numeric with a prd_ prefix (e.g. prd_42). Use the id from your own response in the next step.

Step 4: Make a Purchase

Purchase airtime:

bash
curl -X POST \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_42",
    "phone_number": "08012345678",
    "amount": "100.00",
    "external_reference": "1736234400A1B2C3"
  }' \
  https://my.rizpay.app/api/partners/v1/purchases

Response:

json
{
  "status": { "code": 201, "message": "Purchase created successfully" },
  "data": {
    "id": "txn_abc123",
    "type": "transaction",
    "attributes": {
      "amount": "100.0",
      "currency": "NGN",
      "status": "pending",
      "category": "purchase",
      "description": "Purchase of MTN Airtime",
      "reference": "a1b2c3d4e5f607181736234400",
      "external_reference": "1736234400A1B2C3",
      "product_type": "airtime",
      "phone_number": "08012345678",
      "meter_number": null,
      "price": {
        "product_amount": "100.00",
        "fee_amount": "0.00",
        "total_debit": "100.00",
        "currency": "NGN",
        "basis": "face_value"
      },
      "created_at": "2026-05-18T10:35:00+01:00",
      "updated_at": "2026-05-18T10:35:00+01:00"
    }
  }
}

Tip: The external_reference must be exactly 16 characters: 10-digit Unix timestamp + 6 alphanumeric. See Duplicate Prevention for code examples.

Step 5: Check Status

Poll the transaction status:

bash
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  https://my.rizpay.app/api/partners/v1/purchases/txn_abc123

Response (when complete):

json
{
  "status": { "code": 200, "message": "Purchase details retrieved" },
  "data": {
    "id": "txn_abc123",
    "type": "transaction",
    "attributes": {
      "amount": "100.0",
      "currency": "NGN",
      "status": "successful",
      "category": "purchase",
      "description": "Purchase of MTN Airtime",
      "reference": "a1b2c3d4e5f607181736234400",
      "external_reference": "1736234400A1B2C3",
      "product_type": "airtime",
      "phone_number": "08012345678",
      "meter_number": null,
      "price": {
        "product_amount": "100.00",
        "fee_amount": "0.00",
        "total_debit": "100.00",
        "currency": "NGN",
        "basis": "face_value"
      },
      "created_at": "2026-05-18T10:35:00+01:00",
      "updated_at": "2026-05-18T10:35:02+01:00"
    }
  }
}

The transaction is done when status reaches successful, failed, or reversed. There is no separate completion timestamp: use updated_at.

Simple Node.js Example

javascript
const API_KEY = "sk_live_your_secret_key";
const BASE_URL = "https://my.rizpay.app/api/partners/v1";

// Generate external reference: 10-digit timestamp + 6 alphanumeric
function generateReference() {
  const timestamp = Math.floor(Date.now() / 1000);
  const chars =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  let suffix = "";
  for (let i = 0; i < 6; i++) {
    suffix += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return `${timestamp}${suffix}`;
}

async function purchaseAirtime(phoneNumber, amount) {
  const response = await fetch(`${BASE_URL}/purchases`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_id: "prd_42", // use a product id from GET /products/airtimes
      phone_number: phoneNumber,
      amount: amount,
      external_reference: generateReference(),
    }),
  });

  return response.json();
}

// Usage
purchaseAirtime("08012345678", "500.00")
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Using the Sandbox

For testing, use sandbox credentials:

  1. Create a sandbox API key (sk_test_*)
  2. Use the sandbox endpoint: /api/partners/sandbox/v1
bash
curl -X GET \
  -H "Authorization: Bearer sk_test_your_test_key" \
  https://my.rizpay.app/api/partners/sandbox/v1/account/balance

Sandbox purchases don't charge your account or deliver real airtime. The sandbox only recognizes specific test phone numbers (e.g. 08011111111 for an instant success); any other number fails with PURCHASE_FAILED. The First Purchase guide lists them all and walks the full flow.

Next Steps