> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sandbox.sparkle.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Bill Payment

> Learn how to process bill payments and utility transactions

# 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:

<Steps>
  <Step title="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

    <Accordion title="Sample Request">
      <CodeGroup>
        ```bash cURL theme={null}
        curl -X GET ${API_BASE_URL}/bills/categories \
          -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
          -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
          -H "signature: ${SIGNATURE}"
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Sample Response">
      ```json theme={null}
      {
        "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"
            }
        ]
      }
      ```
    </Accordion>

    <Note>
      Getting biller categories does not require customer consent so therefore there is no need to request for scope to carry out this API call.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Accordion title="Sample Request">
      <CodeGroup>
        ```bash cURL theme={null}
        curl -X GET ${API_BASE_URL}/bills/${category_id}/categories \
          -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
          -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
          -H "signature: ${SIGNATURE}"
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Sample Response">
      ```json theme={null}
      {
        "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"
                  }
              ]
            }
          ]
        }
      }
      ```
    </Accordion>

    <Note>
      Getting billers does not require customer consent so therefore there is no need to request for scope to carry out this API call.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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

    <Accordion title="Sample Request">
      <CodeGroup>
        ```bash cURL theme={null}
        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}"
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Sample Response">
      ```json theme={null}
        {
          "status": "success",
          "message": "Operation successful",
          "data": {
              "Customers": [
                  {
                      "paymentCode": "3|22|GOTV_MAX",
                      "customerId": "4131953321",
                      "responseCode": "90000",
                      "responseDescription": "success"
                  }
              ]
          }
        }
      ```
    </Accordion>

    <Note>
      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.
    </Note>

    <Note>
      The `biller_id` typically looks like `3|22|GOTV_MAX` make sure it is URL encoded.
    </Note>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Get Customer Accounts">
    After successful validation, your application should retrieves all available customer accounts that can be used for payment.

    <Accordion title="Sample Request">
      <CodeGroup>
        ```bash cURL theme={null}
        curl -X GET ${API_BASE_URL}/accounts \
          -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
          -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
          -H "signature: ${SIGNATURE}"
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Sample Response">
      ```json theme={null}
      {
        "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": []
            }
        ]
      }
      ```
    </Accordion>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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
  </Step>

  <Step title="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)

          <Accordion title="Sample Request">
            <CodeGroup>
              ```bash cURL theme={null}
              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"
              }'
              ```
            </CodeGroup>
          </Accordion>

          <Accordion title="Sample Response">
            ```json theme={null}
              {
                "status": "success",
                "message": "Operation successful",
                "data": {
                  
                }
              }
            ```
          </Accordion>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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
  </Step>
</Steps>

## Next Steps

Now that you understand bill payment operations, explore these related topics:

* [Developer Onboarding](/guides/developer-onboarding) - Onboard Developer
* [Customer Management](/guides/customers) - Manage customer information and relationships
* [Account Management](/guides/account) - Manage bank accounts and balances
* [Transfers](/guides/transfers) - Process money transfers between accounts
* [Card Management](/guides/card-management) - Manage Payment Cards
* [Loan Information](/guides/loans) - Access customer Loan Information

<Button href="/api-reference/payments" size="sm">
  Explore Bill Payment APIs
</Button>

<Note>
  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.
</Note>