Electricity | RizPay Developer API

Pay prepaid and postpaid electricity bills for all major Nigerian distribution companies.

Supported Distributors

Code	Name	Region
`IKEDC`	Ikeja Electric	Lagos (Ikeja)
`EKEDC`	Eko Electric	Lagos (Eko)
`AEDC`	Abuja Electric	Abuja
`KEDC`	Kaduna Electric	Kaduna
`JEDC`	Jos Electric	Jos
`IBEDC`	Ibadan Electric	Ibadan
`KAEDC`	Kano Electric	Kano
`EEDC`	Enugu Electric	Enugu
`PhED`	Port Harcourt Electric	Port Harcourt
`BEDC`	Benin Electric	Benin
`ABA`	Aba Power	Aba
`YEDC`	Yola Electric	Yola

Purchase Flow

Electricity purchases require a two-step process:

Verify - Validate the meter number and get customer details
Purchase - Make the payment

This prevents payments to invalid meters.

Step 1: List Products

bash

curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  "https://my.rizpay.app/api/partners/v1/products/electricity?distributor=IKEDC"

Response:

json

{
  "status": { "code": 200, "message": "Success" },
  "data": [
    {
      "id": "prd_ikedc_prepaid",
      "name": "IKEDC Prepaid",
      "type": "electricity",
      "distributor": "IKEDC",
      "meter_type": "prepaid",
      "min_amount": "500.00",
      "max_amount": "500000.00",
      "fee": "100.00"
    },
    {
      "id": "prd_ikedc_postpaid",
      "name": "IKEDC Postpaid",
      "type": "electricity",
      "distributor": "IKEDC",
      "meter_type": "postpaid",
      "min_amount": "500.00",
      "max_amount": "500000.00",
      "fee": "100.00"
    }
  ]
}

Step 2: Verify Meter

Required before purchase. Validates the meter and returns customer details.

bash

curl -X POST \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_ikedc_prepaid",
    "meter_number": "12345678901"
  }' \
  https://my.rizpay.app/api/partners/v1/purchases/verify

Response:

json

{
  "status": { "code": 200, "message": "Success" },
  "data": {
    "verified": true,
    "customer_name": "JOHN DOE",
    "customer_address": "123 Main Street, Ikeja, Lagos",
    "meter_type": "prepaid",
    "meter_number": "12345678901"
  }
}

Verification Errors

Error	Meaning
`VERIFICATION_FAILED`	Invalid meter number
`PRODUCT_UNAVAILABLE`	Distributor service is down

Step 3: Make Purchase

After verification, make the purchase:

bash

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

Response:

json

{
  "status": { "code": 201, "message": "Purchase created" },
  "data": {
    "id": "txn_abc123",
    "reference": "elec-order-001",
    "product_id": "prd_ikedc_prepaid",
    "amount": "5000.00",
    "fee": "100.00",
    "total": "5100.00",
    "status": "pending",
    "meter_number": "12345678901",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Successful Purchase

When the transaction completes, the response includes the token:

json

{
  "status": { "code": 200, "message": "Success" },
  "data": {
    "id": "txn_abc123",
    "status": "successful",
    "token": "1234-5678-9012-3456-7890",
    "units": "45.5 kWh",
    "completed_at": "2024-01-15T10:30:05Z"
  }
}

Important: For prepaid meters, provide the token to the customer. They'll enter it into their meter to load the units.

Complete Example

javascript

// 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 payElectricity(meterNumber, amount, phoneNumber) {
  const API_KEY = "sk_live_your_secret_key";
  const BASE_URL = "https://my.rizpay.app/api/partners/v1";

  // Step 1: Find the product
  const productsRes = await fetch(
    `${BASE_URL}/products/electricity?distributor=IKEDC`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const products = await productsRes.json();
  const product = products.data.find((p) => p.meter_type === "prepaid");

  // Step 2: Verify meter
  const verifyRes = await fetch(`${BASE_URL}/purchases/verify`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_id: product.id,
      meter_number: meterNumber,
    }),
  });

  const verification = await verifyRes.json();
  if (!verification.data.verified) {
    throw new Error("Invalid meter number");
  }

  // Step 3: Make purchase
  const purchaseRes = await fetch(`${BASE_URL}/purchases`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_id: product.id,
      meter_number: meterNumber,
      amount: amount,
      phone_number: phoneNumber,
      external_reference: generateReference(),
    }),
  });

  return await purchaseRes.json();
}

Meter Types

Type	Description	Token
`prepaid`	Pay before use	Yes - customer enters token
`postpaid`	Pay after use	No - payment credits account

Required Scope

Requires the purchase_electricity scope on your API key.

Next Steps

Cable TV - Subscribe to cable TV
Webhooks - Get notified when payment completes