Register

Bills Payment API

The Bills Payment API, a powerful tool crafted to streamline the process of paying bills with ease and efficiency. This documentation serves as your comprehensive guide to leverage our API endpoint seamlessly, enabling you to initiate bills payment transactions, verify payment details, and ensure successful payment.

How does it work?

  1. The client calls the GetAllBills endpoint to get a list of all available billers.

  2. The client validates the customer identifier against selected biller for payment.

  3. The client initiates a bill payment request on behalf of the user, providing necessary payment details such as bill amount and recipient information or customer identifier.

  4. The bank makes a callback to the client using their authorization URL to revalidate bills payment.

  5. Upon successful payment validation, the client gets a PENDING status of the payment, while the transaction is processed.

  6. The client is notified of the payment status via the provided callback URL, informing them of the successful completion or any potential issues with the payment process.

Go Live

Step 1: Get All Bills

Request URL

GET - {baseURL}/bills-payment/api/BillsPayment/GetAllBills

Client sends a GET request to retrieve a list of all available and active billers and their respective biller codes.

This endpoint takes no additional parameters. The expected response model is seen in the block below.

Try it out!

Step 2: Validate Customer Identifier

Request URL

POST - {baseURL}/bills-payment/api/BillsPayment/ValidateCustomer

Try it out!

Client makes a POST request to validate customer's identifier along with the corresponding billerId for any biller. For example, the meter number would be customer identifier in paying electricity bills.

Step 3: Pay Bill

Request URL

POST - {baseURL}/bills-payment/api/Shared/PayBill

Process final bills payment request.

Try it out!

  1. The client initiates a bills payment request on behalf of the customer.

  2. The client must include a valid access key (ClientID) in the request header for authentication purposes.

  3. Client is expected to pass a securityInfo. This should be an encrypted value whose signature is known only by the client. The client should be the only one with the key to decrypt its value. This value serves as the mandate for authorization of bills payment.

  4. The bank makes an authentication request to the client using the securityInfo to confirm the transaction. The client is expected to validate this authentication request for the transaction to be executed. Authentication request and response models can be seen below.

  5. The client gets a PENDING transaction status, while the transaction is being executed.

  6. Client receives final transaction status via a callback URL. This callback serves as a notification that the payment transaction has been processed successfully.

Authentication Model

This webhook is to be provided by the client. It would be called by the bank to authorize payment transactions.

Request Model

  1. The bank makes this request to the client to authorize this transaction request.

  2. Authorization callbackURL is profiled by the bank, and mapped to the clients access key.

  3. Bank makes authentication request to client by passing the securityInfo and custom transactionReference specified in the payout request.

  4. Clients should ensure that the encryption used for the securityInfo param is highly secured, dynamic and unique to each transaction request.

  5. This endpoint should not take any header as it is generic to all clients using this service.

Payment Notification Callback

Clients are to build their callback following the specification below. Your callback URL would be profiled to your assigned channelId.