Process a Bill

The Monnify Bills Payment feature allows all Monnify merchants to Vend and Process Bills using their existing Monnify account. This includes services like Utility Bills, Airtime Topup, and other essential bills.

Info:

Activation: The Bills Payment service is not active for all Monnify Merchants by default. To enable it for your account, you must send an activation request via email to: [email protected].

Authentication

Access to the Bills Payment product is secured using Bearer Token authentication.

To use the service, you must first obtain an Access Token by authenticating with your API Key and Client Secret, which are available on your Monnify dashboard. This token must be included in the header of all subsequent requests to prove your identity as a merchant.

Bill Payment Workflow

Integrating the Bill Payment product involves a high-level sequence of steps to ensure customers select the correct service and that their details are validated before any funds are debited.

Step	Action	Description	Key Requirement
1	Get Categories	Display a list of general bill types (e.g., ELECTRICITY, CABLE_TV) for the user to select from.	None
2	List Billers	Show all available service providers (e.g., specific electricity companies) that fall under the selected category.	Category Code
3	List Products	Fetch the specific products offered by the selected biller (e.g., Prepaid Meter, Postpaid Meter, various Data Bundles).	Biller Code
4	Validate Customer	Required Step. The customer enters their unique identifier (e.g., meter number, phone number). The system validates these details before payment can proceed.	Product Code & Customer ID
5	Process/Vend Bill	Once validation is successful, initiate the actual payment transaction by sending the amount and the unique validation reference.	Validation Reference
6	Verify Status	Check the status of a transaction if it initially failed or is pending, or use this to retrieve the token or unit information for the customer.	Transaction Reference

How it works

Consuming the Monnify Bills Payment service generally involves three primary phases: Discovery, Validation, and Vending.

Discovery (Finding Billers and Products)
Before a payment can be processed, you must identify the relevant biller and product using the following endpoints:
- Retrieve Biller Categories: Use the GET Biller Categories endpoint to list all available categories (e.g., ELECTRICITY, DATA, CABLE_TV).
- Retrieve List of Billers: Use the GET Billers endpoint to retrieve all active billers available for payment. This list can be filtered using the categoryCode.
- Retrieve Available Products: Use the GET Billers product endpoint to fetch a list of available products offered by different billers. This list must be filtered using the specific billerCode.
Validation (Verifying Customer Details)
Validation is a required step before executing the final payment.
- Endpoint: Customer details are validated using the POST method on validate customer.
- Request Payload: The request requires the productCode and the customerId.
- Successful Response: A successful validation will return a validationReference within the vendInstruction body. This reference is crucial for the subsequent payment step.
Vending (Executing Payment)
This step executes the bill payment, resulting in a charge to the customer.
- Endpoint: Bill payment is processed using the POST method on vend.
- Required Inputs: The request must include the productCode, customerId, a merchant-supplied vendReference (such as `RANDOM_REF`), and the vendAmount.
- Validation Reference Requirement: You must include a validationReference obtained from the successful validate customer call in the vend request.
- Successful Vend: A successful call returns a response body that includes the Monnify generated transactionReference, the Merchant’s suppliedvendReference, and the vendStatus, which should be "SUCCESS" for a completed payment.
- Status Check/Retry: If necessary (e.g., if a vend is initially reported as IN_PROGRESS), merchants can verify the status or retry bill processing using the POST method on Bills payment requery.

Key Concept: Pre-Validation

The Validation step (Step 4) is critical. Before you can process a bill (Step 5), you must successfully validate the customer's ID against the chosen product. A successful validation generates a unique Validation Reference, which acts as a secure key required to successfully complete the final Vend request. This ensures that the payment is directed to the correct customer account.