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": "Success" },
  "data": {
    "balance": "50000.00",
    "currency": "NGN",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

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": "Success" },
  "data": [
    {
      "id": "prd_mtn_airtime",
      "name": "MTN Airtime",
      "type": "airtime",
      "network": "MTN",
      "min_amount": "50.00",
      "max_amount": "50000.00",
      "fee": "0.00"
    }
  ]
}

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_mtn_airtime",
    "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" },
  "data": {
    "id": "txn_abc123",
    "external_reference": "1736234400A1B2C3",
    "amount": "100.00",
    "fee": "0.00",
    "total": "100.00",
    "status": "pending",
    "phone_number": "08012345678",
    "created_at": "2024-01-15T10:35:00Z"
  }
}

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": "Success" },
  "data": {
    "id": "txn_abc123",
    "status": "successful",
    "completed_at": "2024-01-15T10:35:02Z"
  }
}

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_mtn_airtime",
      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.

Next Steps