Bill lookup
The bill lookup transaction is an API call that verifies a consumer's reference number and returns the details of any outstanding bills associated with that reference. Depending on the type of bill, the reference number could be:
- National ID number
- Traffic fine notice number
- Account reference number
- Multichoice number
The details returned in the bill lookup response are used to populate the bill payment request message.
The reference used will be based on the chosen routing and is also related to specific biller (e.g., a Multichoice reference being used for DSTV bills).
Some service providers may allow for multiple bills to be returned under one reference number. For example, an ID number reference may return multiple traffic fines.
Pay@ is the only service provider that currently supports multiple bills, and only for traffic fines.
Operation and Messages
A bill lookup consists of a single set of messages described by the lookupBills operation, GET/bills:
- Response payload:
BillLookupResponse - Error payload:
ErrorDetail
Message Flows
The sections below describe a successful bill lookup and error scenarios.
Successful Bill Lookup
- The originating system sends a
GETcall to the/bills/ {referenceNumber}API endpoint (lookupBillsoperation). - Electrum responds with a
BillLookupResponsemessage payload containing the details (amount due, minimum amount, maximum amount and whether it is over payable) of any bills associated with that reference number.
Error or Timeout at Originating System
- The originating system sends a
GETcall to the/bills/ {referenceNumber}API endpoint (lookupBillsoperation). - An error occurs at the originating system, or a timeout occurs when the response message does not reach the originating system. No further action is required.
Error at Electrum or Service Provider
- The originating system sends a
GETcall to the/bills/ {referenceNumber}API endpoint (lookupBillsoperation). - An error occurs at Electrum or the service provider.
- Electrum sends an HTTP status of
400,500,501,503, or504and anErrorDetailmessage to the originating system. No further action is required.
What happens if you already paid the bill?
If you do a Bill Lookup on a bill that has already been paid, then the lookupBills function returns an error based on set conditions, such as the amount due, minimum and maximum amounts, and whether it can be overpaid. If the bill allows overpayment, it returns a balance along with the minimum and maximum amounts.
Electrum will not validate billers on a client’s behalf. If we receive a request to pay for a bill, we will never decline it and will immediately forward it upstream.