{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-vas/vas.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Bill lookup","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"bill-lookup"},"children":["Bill lookup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["National ID number"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Traffic fine notice number"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Account reference number"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Multichoice number"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The details returned in the bill lookup response are used to populate the bill payment request message."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pay@ is the only service provider that currently supports multiple bills, and only for traffic fines."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operation-and-messages"},"children":["Operation and Messages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A bill lookup consists of a single set of messages described by the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/other/lookupbills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lookupBills"]}]}," operation, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET/bills"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/schema/billlookupresponse"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BillLookupResponse"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Error payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/schema/errordetail"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorDetail"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"message-flows"},"children":["Message Flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sections below describe a successful bill lookup and error scenarios."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"successful-bill-lookup"},"children":["Successful Bill Lookup"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/bills/ {referenceNumber}"]}," API endpoint (",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/other/lookupbills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lookupBills"]}]}," operation)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum responds with a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/schema/billlookupresponse"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BillLookupResponse"]}]}," message payload containing the details (amount due, minimum amount, maximum amount and whether it is over payable) of any bills associated with that reference number."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/successful-bills-lookup.3fdc0f67d8ddf4527449f7afe876c4ecfbfc08a98aeba4ffb70a9d539a25567c.45baa1d1.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-or-timeout-at-originating-system"},"children":["Error or Timeout at Originating System"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/bills/ {referenceNumber}"]}," API endpoint (",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/other/lookupbills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lookupBills"]}]}," operation)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/error-at-os-during-bills-lookup.36f2a0822379a391981e0e66bb9160306cadd2b95cc6a9c86a57fcb00c8f57e3.45baa1d1.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-at-electrum-or-service-provider"},"children":["Error at Electrum or Service Provider"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/bills/ {referenceNumber}"]},"API endpoint (",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/other/lookupbills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lookupBills"]}]}," operation)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs at Electrum or the service provider."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum sends an HTTP status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["501"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["504"]}," and an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/schema/errordetail"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorDetail"]}]}," message to the originating system. No further action is required."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/error-at-sp-during-bills-lookup.2e4e6a97866eb536279c07e8609d8151a6152c7e492d1ca7179fb4b05e14c66e.45baa1d1.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-happens-if-you-already-paid-the-bill"},"children":["What happens if you already paid the bill?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you do a Bill Lookup on a bill that has already been paid, then the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/billpay/swagger/other/lookupbills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]}]},"headings":[{"value":"Bill lookup","id":"bill-lookup","depth":1},{"value":"Operation and Messages","id":"operation-and-messages","depth":2},{"value":"Message Flows","id":"message-flows","depth":2},{"value":"Successful Bill Lookup","id":"successful-bill-lookup","depth":2},{"value":"Error or Timeout at Originating System","id":"error-or-timeout-at-originating-system","depth":2},{"value":"Error at Electrum or Service Provider","id":"error-at-electrum-or-service-provider","depth":2},{"value":"What happens if you already paid the bill?","id":"what-happens-if-you-already-paid-the-bill","depth":2}],"frontmatter":{"seo":{"title":"Bill lookup"}},"lastModified":"2026-04-08T11:09:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/vas/public/bill-payments/integrate-your-channel/bill-lookup","userData":{"isAuthenticated":false,"teams":["anonymous"]}}