​
Bill Payment Guide

This guide covers everything you need to know about processing bill payments and utility transactions in your Open Banking application, from electricity bills to airtime purchases.

​
Overview

Bill payment functionality is a crucial component of any modern banking application. Our API supports comprehensive bill payment operations that allow you to process payments for various utilities, services, and bills. This functionality enables you to provide convenient payment solutions for your customers’ everyday needs.

​
Bill Payment Flow

The bill payment process follows a structured flow to ensure accurate payments and proper validation. Here’s the complete step-by-step process:
1

Get Biller Categories

The first step in the bill payment process is to retrieve all available bill payment categories. This provides users with an organized view of different types of bills they can pay. Categories include:
  • Electricity
  • Water
  • Cable TV & Internet
  • Airtime & Data
  • Education
  • Insurance
  • Government & Taxes
  • Others
curl -X GET ${API_BASE_URL}/bills/categories \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "success",
  "message": "Operation successful",
  "data": [
      {
          "id": 1,
          "name": "Airtime",
          "description": "Airtime Recharge"
      },
      {
          "id": 2,
          "name": "Data",
          "description": "DATA SUBSCRIPTION"
      },
      {
          "id": 3,
          "name": "TV",
          "description": "TV Subscription"
      },
      {
          "id": 4,
          "name": "Electicity",
          "description": "ELECTRICITY"
      },
      {
          "id": 5,
          "name": "Internet",
          "description": "Internet Services"
      },
      {
          "id": 6,
          "name": "Betting",
          "description": "Betting"
      },
      {
          "id": 7,
          "name": "Church Collections",
          "description": "Church"
      },
      {
          "id": 8,
          "name": "EVENTS",
          "description": "EVENTS"
      },
      {
          "id": 9,
          "name": "Education",
          "description": "Education"
      }
  ]
}
Getting biller categories does not require customer consent so therefore there is no need to request for scope to carry out this API call.
2

User Selects Category

Once the categories are displayed, the user selects the appropriate category for the bill they want to pay. This selection helps narrow down the available billers and provides a better user experience.
3

Get Billers in Category

After category selection, the application uses the selected category ID to retrieve all billers within that category. This returns a list of specific service providers or billers that the user can choose from.For example, if the user selects “Electricity”, the system will return all electricity distribution companies available for payment.
curl -X GET ${API_BASE_URL}/bills/${category_id}/categories \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "success",
  "message": "Operation successful",
  "data": {
    "billers": [
      {
        "category_id": 3,
        "id": "2|6|COMPACT",
        "name": "COMPACT",
        "products": [
            {
                "id": "2|6|COMPACT",
                "name": "COMPACT",
                "reference_prompt": null,
                "currency": null,
                "fee": 0,
                "fixed_amount": "1570000"
            }
        ]
      },
      {
        "category_id": 3,
        "id": "2|7|COMPACT_PLUS",
        "name": "COMPACT_PLUS",
        "products": [
            {
                "id": "2|7|COMPACT_PLUS",
                "name": "COMPACT_PLUS",
                "reference_prompt": null,
                "currency": null,
                "fee": 0,
                "fixed_amount": "2500000"
            }
        ]
      }
    ]
  }
}
Getting billers does not require customer consent so therefore there is no need to request for scope to carry out this API call.
4

User Selects Biller

The user then selects the specific biller from the list of available billers in the chosen category. This could be their electricity company, water authority, or any other service provider.
5

Enter Biller Reference

The application prompts the user to enter their biller reference number. This could be:
  • Meter number (for utilities)
  • Account number
  • Customer ID
  • Phone number (for airtime)
  • Student ID (for education fees)
  • Policy number (for insurance)
6

Validate Biller Reference

The application calls the bill validation API to verify the reference number with the selected biller. This validation ensures:
  • The reference number exists
  • It belongs to the customer
  • Current outstanding amount (if applicable)
  • Due date information
  • Account holder name confirmation
curl -X GET ${API_BASE_URL}/bills/${category_id}/billers/${biller_id}/reference/${bill_reference} \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

  {
    "status": "success",
    "message": "Operation successful",
    "data": {
        "Customers": [
            {
                "paymentCode": "3|22|GOTV_MAX",
                "customerId": "4131953321",
                "responseCode": "90000",
                "responseDescription": "success"
            }
        ]
    }
  }
Make sure you send the scope bills.bill.validate while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.
The biller_id typically looks like 3|22|GOTV_MAX make sure it is URL encoded.
The bill_reference is the biller issued customer id e.g. for DSTV it is your decoder number, for airtime it is your phone number.
7

Get Customer Accounts

After successful validation, your application should retrieves all available customer accounts that can be used for payment.
curl -X GET ${API_BASE_URL}/accounts \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "success",
  "message": "Operation successful",
  "data": [
      {
          "customer_id": "c3641f2e-3082-4ca6-96e2-086ef82c10c4",
          "account_name": "Hello Dev",
          "account_number": "1000000350",
          "product_id": "Personal",
          "currency_code": "NGN",
          "account_opening_date": "2025-05-15",
          "account_type": "Current",
          "bvn": "234802325829",
          "phone": "2348023258292",
          "email": "hellodevelo+1@gmail.com",
          "custom_properties": []
      },
      {
          "customer_id": "c3641f2e-3082-4ca6-96e2-086ef82c10c4",
          "account_name": "Reverb",
          "account_number": "1000000367",
          "product_id": "Business",
          "currency_code": "NGN",
          "account_opening_date": "2025-05-20",
          "account_type": "Current",
          "bvn": "234802325829",
          "phone": "2348023258292",
          "email": "hellodevelo+1@gmail.com",
          "custom_properties": []
      }
  ]
}
Make sure you send the scope accounts.list.readonly while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.
8

User Selects Account

The customer selects which account they want to use for the bill payment. Your application should display account details with sufficient information for customer to decide which account to use e.g. Account Name, Account NUmber, Account Balance etc
9

Process Bill Payment

The application calls the bill payment API with the following parameters:
  • Selected account number
  • Selected biller information (category ID, Biller ID, Product ID)
  • Payment amount
  • Payer info (Information about the payer e.g. Name. email, phone)
  • Any additional required information (To be passed in customer Properties) 
    curl -X POST ${API_BASE_URL}/bills/${category_id}/billers/${biller_id}/reference/${bill_reference} \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}" \
  -d '{
    "biller_id": "3|639|GOTV_RENEW",
    "bill_reference": "4131953321",
    "category_id": 3,
    "source_account_number": "1000000219",
    "amount": "1000.0",
    "customerMobile":"2348160269909",
    "customerEmail":"wizston@gmail.com"
}'

      {
    "status": "success",
    "message": "Operation successful",
    "data": {
      
    }
  }
Make sure you send the scope bills.transactions.create while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.
10

Handle Payment Response

Based on the payment response, the application displays an appropriate message to the customer:Successful Payment:
  • Payment confirmation
  • Transaction reference number
  • Payment receipt
  • Success message
Failed Payment:
  • Error message explaining the failure
  • Suggested resolution steps
  • Option to retry payment

​
Next Steps

Now that you understand bill payment operations, explore these related topics:
Always follow the complete bill payment flow to ensure accurate payments. Validate biller references and customer account details before processing payments. Implement robust security measures and provide clear user feedback throughout the payment process for successful bill payment operations.
⌘I