Documentation

Our API has three main blocks. Block 1 – Biller catalogs BILRS’s API provides access to an online biller catalog that lists all the billers, products and services available to transact, along with important information related to each one. Our catalog has three distinct levels: BillerCatalog endpoint lists all the billers available for all countries. SKUCatalog endpoint lists all the payment options available for a biller (e.g., accepts partial payments, accepts excess payments, accepts past due payments, minimum/maximum payment value permitted, etc). IOCatalog endpoint lists all the input references required to transact with a biller (e.g., account number, telephone number, customer ID). Most billers only require one input, but some may require more than one input. Block 2 – Transaction processing The bill payment transaction flow depends on whether a biller offers the functionality for a user to query the amount owed for an account (i.e., balance inquiry). Biller Offers Balance Inquiry Functionality AmountDue endpoint must be called to obtain the most recent amount owed balance from the biller prior to processing a payment if ‘InquiryAvailable’ = 1 in SKUCatalog endpoint. ∙ ProcessPayment endpoint will be used to process an AmountDue reponse. You will be required to copy the value obtained in field Output1 from the AmountDue response into field Input1 of the ProcessPayment request. Biller does NOT Offer Balance Inquiry Functionality ProcessPayment endpoint must be used for those billers that do not offer balance inquiry functionality (‘InquiryAvailable’ = 0). VerifyPaymentStatus endpoint may be called to verify the status of a transaction for any reason. Block 3 – Other endpoints Our API includes additional endpoints: Echo endpoint can be used to confirm connectivity with our Platform DailyFXRate provides information on the FX rates for the day.

Once you generate the API token in the administration dashboard, you can add that token in the request headers as the authorization parameter on a Bearer token. Ex. { ‘headers’: { ‘Content-Type’: ‘application/json’, ‘Authorization’: ‘Bearer {API TOKEN}’ } }

The Token is static for each of our clients, all requests from you will use the same Token. For security purposes, BILRS will suggest you to update the token each 6 months on the administration portal.

Our catalogue can change any day, although changes tend to be less frequent. The catalogue may be updated to reflect a new Biller, to disable a Biller that becomes unavailable or to update any of the fields related to an existing Biller. Our catalogue contains a field called “CatalogVersion” that automatically updates when a change occurs to the catalogue. “CatalogVersion” can be reviewed at any time by invoking the BillerCatalog or Echo endpoint to see whether any changes have been made to our catalogue. We recommend our clients to schedule a task that checks the ‘CatalogVersion’ once a day and, if there is a version change, update all three catalogue levels – BillerCatalog, SKUCatalog, IOCatalog. An update should not take more than a few minutes. Our technical team will discuss with your integration team the best options for managing the catalogue. That said, we have designed our catalogue so that no additional back-end development work is required when we add a new country or biller.

We recommend that you keep a local copy of our catalogs and check for updates at least once a day.

You will not receive a separate communication announcing a new catalog version. Please note that our commercial team may send a communication announcing new countries and billers, but this should not displace our recommendation that you check the ‘CatalogVersion’ daily.

It depends. Many prepaid billers only allow specific purchase amounts (e.g., 10, 20, 50, 100). For those billers, each amount will be a separate SKU hence the reason a biller may have more than one SKU. Billers may also have more than one SKU to separate distinct services. For example, a biller that offers both water and electricity services may have an SKU for each type of service. A biller may also have more than one SKU for two different inputs. For example, the biller allows the user to enter either an account number of mobile number to execute a transaction. If a SKU has Amount > 0 in the SKUCatalog, then a payment for that biller will only be successful if the amount sent in the Payment request is equal to the amount configured for the biller in the SKUCatalog. If a SKU has Amount = 0 in the SKUCatalog, then it can accept any payment amount within the limits set in MinAmount and MaxAmount, and which abide by the rules regarding partial/excess/past due payments.

Some billers may require the user to enter more than one input reference to query the amount owed on the account or process a payment. If a biller requires more than one input, this information will be concatenated, delimited by a pipe ‘|’ and sorted by the IOID field in the IOCatalog.

We parse the information you send us into biller-specific field mappings. Any extraneous information sent different than what we anticipate will likely cause the transaction to fail. Any required inputs not sent will also likely cause the transaction to fail. All inputs in the IOCatalog are mandatory to transact.

This information can be found in our SKUCatalog, which has a field for each biller called ‘InquiryAvailable’. A biller offers balance inquiry functionality if ‘Inquiry Available’ = 1.

Yes, it is MANDATORY to execute the AmountDue endpoint for those billers that offer balance inquiry functionality (‘InquiryAvailable’ = 1). Otherwise, you will not be able to invoke the PaymentProcess endpoint.

The request will fail with a ResponseCode ‘11’ (‘Inquiry Not Available for SKU’).

The IOCatalog provides the exact name of the input reference required by the biller as well as additional information on the minimum and maximum length of the input reference and whether the input reference is numeric or alphanumeric.

Please see the API technical specification documentation for the list of mandatory and optional fields required to be sent in the request message.

No, BILRS does not perform any validation of the minimum/maximum length, nor on whether the input sent is numeric or alphanumeric. Those validations should be done on your side prior to sending the balance inquiry request.

We consider calls to the AmountDue endpoint a transaction, which is why we expect a value for EntityTransactionID in calls to the AmountDue endpoint. This helps us troubleshoot any issue that may arise with a balance inquiry request. Alternatively, you may send a timestamp as the EntityTransactionID. Although not ideal, you can also send a fixed value in this field, since we do not check for duplicate transactions in this endpoint; however we do not recommend this approach.

Our technical team asks that you set a timeout of 60 seconds for the balance inquiry, although most billers respond in less than 20 seconds, if not faster. You can resend a balance inquiry request if for any reason you receive a timeout.

It depends on the biller. The balance inquiry function will return the amount owed from the biller. Some billers may return additional information such as the due date, number of bills due and, in some cases, the name on the account with the biller (i.e., the beneficiary).

The BIllAmountDue will always be expressed in the currency indicated for that biller in the SKUCatalog.

The Currency in the SKUCatalog shows the applicable currency for that SKU, which is typically the local currency for Biller in that country (e.g., PKR in the SKUCatalog for electricity billers in Pakistan). The SettlementCurrency is the same as the Currency in the SKUCatalog, essentially the local currency. The BaseCurrency refers to the currency used for transaction settlement and reconciliation, such as USD.

Our technical team can provide more detailed information on best practices as it relates to your integration with our platform. BILRS has designed our platform and catalogue to be dynamic so any new additions, changes, deletions, updates to the biller information can be immediately reflected in the service to your customer without any additional development work required. The information contained in the catalogues should be used to ensure a simple and seamless payment experience for your customers and minimize any potential causes of friction. Examples of how to leverage the information in our catalogue include: Easily communicate the specific input reference set by the biller for balance inquiry (e.g., Biller 1 – Service # / 12 characters / alphanumeric; Biller 2 – Telephone # / 10 digits/ numeric). It should be dynamic; do not use a static ‘Account Number’ description for all billers as customers will look for that specific input reference on the biller’s invoice. Notify customers when the transaction should be reflected with the biller (e.g., real time, 2 business days). Important for two reasons: 1) Reduce number of inbound customer inquiries asking for the status of the payment; 2) Some markets, like the U.S., require you to communicate when the transaction will be reflected with the biller. Use information to immediately flag transaction if customer inputs information outside the parameters established by the biller (e.g., input reference exceeds min/max length; customer enters input reference as alphanumeric when it can only be numeric; the payment amount exceeds max value permitted by biller). Reference validation done in the front end makes for a better user experience.

The vast majority of billers that offer balance inquiry make it available 24/7. Occasionally a biller may be temporarily unavailable for balance inquiry, payment or both. Our Operations team will send out an email reporting the issue as well as an update when it has been resolved.

In most cases, the values for BillAmountDue and TotalAmountDue will be the same, except when the Biller makes it mandatory to pay each bill individually. Please see the question regarding the handling of past due payments.

A user can pay a past due biller only if allowed by the biller. A past due payment will be accepted for a biller if the field ‘PastDuePaymentAllowed’= 1 in the SKU catalog.

Typically, billers offer one of two payment methods for past due payments: Pay All Pending Invoices at Once: In this approach, the biller adds up all past due bills, so that the user pays all outstanding balances in one lump sum payment. When you perform a bill inquiry, the response will contain the same amount in BillAmountDue and TotalAmountDue. The BillAmountDue includes all outstanding debts and can be paid all at once or in parts if the biller allows partial payments. Pay Each Pending Invoice Individually: A few billers that allow past due payments make it mandatory for the user to pay each bill individually. On those occasions, the AmountDue response will return BillsDue > 1, and BillAmountDue wil not be equal to the TotalAmountDue. For those billers, BillAmountDue represents the amount to be paid (typically the oldest bill first), and TotalAmountDue is the sum of all bills. For example, a balance inquiry returns the following BillsDue = 3 TotalAmountDue = 1000 BillAmountDue = 400 In this example, the user will be permitted to pay the bill for 400. After completing that payment, a subsequent balance inquiry would return BillsDue = 2, TotalAmountDue = 600, with maybe the next BillAmountDue = 200. If the Customer pays that second bill successfully, the next bill inquiry should return BillsDue = 1, TotalAmountDue = 400, and BillAmountDue = 400. After paying that third and final bill, a new bill inquiry would return BillsDue = 0, TotalAmountDue = 0, BillAmountDue = 0. The User cannot select which bill or the order in which they want to pay. The balance inquiry will automatically select the next payable bill based on the biller’s business rules.

Yes, you may allow a user to send a payment as long as permitted by the biller (i.e., accepts partial payments) and the amount sent conforms with the minimum and maximum amount rules established by the biller.

It depends on whether or not the biller offers balance inquiry functionality. Biller Offers Balance Inquiry Functionality: If the response from the AmountDue endpoint is successful, you must send the value obtained in field Output1 from the AmountDue endpoint in field Input1 of the ProcessPayment endpoint. Biller does NOT Offer Balance Inquiry Functionality: The user will need to provide the input reference(s) as defined by the biller in the IOCatalog as well as the amount to be paid. Again, this information must conform with the parameters established by the biller regarding the input reference (i.e., type of reference, numeric/alphanumeric, min/max length, etc) and the amount (i.e., min/max, partial payments, excess payments, past due payments).

Please see the API technical specification documentation for the list of mandatory and optional fields required to be sent in the request message.

ResponseCode ‘00’ = ‘Process Complete’; means that the biller accepted the payment and processed the transaction successfully ResponseCode ‘10’ = ‘Transaction In Progress’; means that the transaction is still being processed by the biller and does not have a final status; once the biller accepts the payment the transaction will be updated to ResponseCode ‘00’; the transaction will be assigned another ResponseCode if the biller rejects the payment. Any response codes other than ‘00’ and ‘10’ indicate there was some error processing the payment and that it has been rejected. Please refer to the API documentation for a complete description of all possible response codes our platform may return.

Yes, you should treat a ResponseCode ’00’ (Process complete) as the final status for the transaction. However, the biller may take up to a few days to post payment to the customer’s account. Our biller SKUCatalog provides information on the maximum time it takes for a transaction to post using the fields “DaysToPost” and “BusinessDays”. DaysToPost shows how many days it may take for the Biller to apply the payment. If you see that a Biller says 0 days, then the payment will be posted the same day as it was received. BusinessDays shows whether the “DaysToPost” value mentioned refers to Business days (BusinessDays = 1) or Calendar days (BusinessDays = 0). Please note that Business Days refers to the country where the payment will be posted.

There is no option for recalling or cancelling a payment once the payment has been authorized and you have received a ResponseCode ‘00’ (Process Complete) as BILRS immediately sends the payment to the biller.

We send the Biller the payment details as we receive them, so we would proceed according to the input sent. Your customer service team will be responsible for establishing its own policies and procedures for handling complaints when one of your customers pays a wrong account number.

The biller will reject the payment and you will receive a ResponseCode ‘08’ (Invalid amount) from our platform.

The biller will reject the payment and you will receive a ResponseCode ‘08’ (Invalid amount) from our platform.

The biller will reject the payment and you will receive a ResponseCode ‘18’ (Amount out of allowed range) from our platform.

The biller will reject the payment and you should receive a ResponseCode ‘17’ (Account Status Invalid) or possibly ResponseCode ‘07’ (Invalid Reference) from our platform.

A transaction that fails due to ResponseCode ‘02‘(Insufficient Funds) means that you do not have enough funds available enabled on the BILRS platform to cover the payment request. Resending the transaction will return the same response code. You will need to request your Finance team to transfer prefunding or settlement funds to BILRS so that new payment requests can be processed.

We recommend setting the timeout for 60 seconds and include automatic calls to the VerifyPaymentStatus endpoint if a timeout occurs.

Yes, but it is important to recognize that this may affect transaction volume. Individuals sometimes make a partial payment or pay more than the amount owed to take advantage of when they have money in their pocket. This behaviour is quite common for many biller types, particularly as it relates to satellite and cable TV.

You should assume that the transaction has posted appropriately. Any queries regarding the status of a specific bill payment transaction should be addressed by submitting a ticket via our Customer Service Desk.

Our biller SKUCatalog provides the maximum time it takes for a transaction to post with a biller. We recommend that you include a message to the customer in the receipt leveraging the “DaysToPost” and “BusinessDays” information, communicating when the transaction will be reflected with the biller.

Possible, but highly unlikely. Our Operations team will contact your customer service team in case a biller reports that they were unable to post a payment that they previously received and marked as successful.

The VerifyPaymentStatus endpoint may be useful for a number of different situations, including: You do not receive a response from BILRS when you use the PaymentProcess endpoint to process a bill payment transaction You receive response code ’10’ (‘Transaction in progress’) and need to check whether the status of the transaction has changed to ResponseCode ‘00’ or other response code indicating that the transaction has been rejected Confirm the status of the transaction for the user as part of your customer service operations

You need the original transaction id that you sent in the EntityTransactionID field for the payment request.

You will need to send the transaction id from the original payment request in the EntityTransactionIDVerify field. The EntityTransactionID field can be used to identify this verification request. If you do not wish to identify each verification request with its own id, you can send the same value in both fields (EntityTransactionID from the ProcessPayment request).

The transaction flow should automatically call the VerifyPaymentStatus when a timeout occurs in the payment request, or when the ResponseCode is 10 ‘Transaction in progress’. If you operate a retail branch/agent network, we strongly recommend that you include the VerifyPaymentStatus method as part of the branch/agent portal functionality. This way the branch/agent location can perform the VerifyPaymentStatus themselves without having to call your call center, which reduces transaction time for your customer. You may also want to enable this functionality in your call center, so that your representatives can provide a real-time answer to any customers that calls enquiring as to the status of a bill payment transaction.

The FXRate returned from DailyFXRate is the rate that is valid for the day stated in FXDate, in Coordinated Universal Time (UTC). The IndicativeFXRate shows an FX rate that was valid at the moment of the call to the AmountDue endpoint and can be used as a reference. We call it “indicative” because it is not locked in since we have no confirmation that a payment will be made for the account.