Bill Payments Service Interface Release Notes

v4.19.0 - 22 October 2025

• Added new paymentOriginatorDetailsRequired field to lookUpBills and accountLookup responses.
• Added new error type PAYMENT_ORIGINATOR_ERROR

v4.18.0 - 13 March 2025

• Added new field idType to Customer class to fulfil FATF requirements.

v4.17.0 - 12 September 2024

• Renamed the API from Bill Payments to Account Payments. Description and names have been updated to reflect the new name. No operation impacts.

v4.16.1 - 04 September 2024

• Updated the merchantId field regex in the LookupBills operation to reflect that spaces are allowed in the merchantId.

v4.16.0 - 28 January 2024

• Added new query parameter originatorCountryCode to API operation lookupBills.

v4.15.0 - 22 September 2023

• Added new paymentStatus operation.
• Added new enums REFUND and VOID for the BasicReversal model’s reversalReason.
• Validation for the following fields was updated:
  • The pinBlock field within the EncryptedPin model has been updated to permit either a 16-character or a 32-character hexadecimal string composed of characters ‘0’ to ‘9’, ‘a’ to ‘f’ (or ‘A’ to ‘F’). It originally only accepted a 16-character length.
  • The field value within the TransactionLabel model has been updated to accept the characters '.' and '/'.

v4.14.0 - 23 January 2023

• Added new lookupBills operation.
• Deprecated requestTrafficFineInfo, requestAccountInfo, and requestPolicyInfo operations. These have been replaced by the lookupBills operation.
• Deprecated createPolicyPayment operation.

v4.13.0 - 12 July 2022

• Added ErrorDetail.ErrorTypes related to the Payments API for error mappings from the Payments API to the Billpay API.

v4.12.0 - 17 August 2021

• Added a customer field to the BillpayRequest class.
• Added the new ErrorType CUSTOMER_ACCOUNT_ERROR.

v4.11.0 - 17 June 2021

• Added a /listBillers operation together with the Category and Biller model definitions.

v4.10.0 - 17 June 2021

• Non-functional refactoring.

v4.9.0 - 2 October 2020

• Non-functional refactoring.

v4.8.1 - 11 March 2020

• Fixed swagger generation to correctly include BillpayAmounts amounts field for the following models:
  • PaymentRequest
  • PolicyPaymentRequest
  • TrafficFinePaymentRequest

v4.8.0 (Deprecated) - 6 March 2020

Deprecated, replaced with v4.8.1. This version resulted in the following issues, which have been fixed in version 4.8.1: A breaking change to the API where the amounts field was dropped from the PaymentRequest, PolicyPaymentRequest, and TrafficFinePaymentRequest models.

• Replaced Amounts in the following models with BillpayAmounts in order to facilitate maximum and minimum payment amounts:
  • BillpayResponse (extended by PaymentResponse, PolicyPaymentResponse and TrafficFinePaymentResponse)
  • PaymentRequest
  • PolicyPaymentRequest
  • TrafficFinePaymentRequest
• Added new field region to BankAccount model for scenarios where the routingCode is not sufficient to uniquely identify a bank account.
• Added new field emailAddress to Customer model.
• Added new Account.AccountType value CASH_PICKUP for cash pickup scenarios.
• Added new models:
  • Pin a base PIN model
  • PinClear for PINs in the clear
  • PinEncrypted for encrypted PIN blocks with the PIN block format, accountNumber and the key index
• Pin was added to CardPayment, taking precedence over the existing encyptedPin field
• Added new models:
  • ExchangeRate to describe the exchange rate between two currencies.
  • Account to describe more varied accounts in a consistent manner. This has the following sub-types defined:
    • BankAccount
    • IbanAccount
    • IfsAccount
    • SwiftAccount
    • MobileWalletAccount
• The limitations on the id field of the Institution model have been removed to make the field suitable for a wider range of applications. The values in this field need no longer be defined by Electrum and similar values as recognised at third parties may now be carried in this field. However, care should be taken during implementation to ensure that different parties agree on the values which will be present in these fields.
• Added explicit fields for STAN and RRN values to BasicAdvice and Transaction models.
• Made the msisdn field of the Customer object an optional field.
• Added a CardPayment payment method.

v4.7.5 - 11 June 2019

• Added the following ErrorTypes: BELOW_MINIMUM_ALLOWED_AMOUNT and ABOVE_MAXIMUM_ALLOWED_AMOUNT

v4.7.4 - 02 May 2019

• Modified PAYMENT_NOT_ALLOWED_USING_SETTLEMENT_ENTITY to BLOCKED_USING_SETTLEMENT_ENTITY

v4.7.3 - 02 May 2019

• This version has been deprecated
• Added the following ErrorTypes: RECEIVER_BLACKLISTED, LUHN_CHECK_FAILED, and PAYMENT_NOT_ALLOWED_USING_SETTLEMENT_ENTITY

v4.7.2 - 13 February 2019

• Non-functional refactoring.

v4.7.1 - 9 January 2019

• Non-functional refactoring.

v4.7.0 - 9 January 2019

• Added Tender and PaymentsMethods fields to PaymentRequest and PaymentResponse
• Added Customer fields to PaymentRequest

v4.6.0 - 31 August 2018

• Non-functional refactoring.

v4.5.0 - 8 November 2017

• Added optional barcode field to SlipLine which represents a barcode on a till slip.

v4.4.3 - 9 October 2017

• Non-functional refactoring.

v4.4.2 - 6 October 2017

• Defined due date format in responses as yyyy-MM-dd

v4.4.1 - 15 Aug 2017

• Non-functional refactoring.

v4.4.0 - 10 Aug 2017

• Non-functional refactoring.

v4.3.1 - 25 July 2017

• Fixed resource base path in Swagger.

v4.3.0 - 24 July 2017

• Added INVALID_MERCHANT ErrorType.

v4.2.0 - 05 January 2017

• Added the following RequestType enumerated values to ErrorDetail:
  • TRAFFIC_FINE_LOOKUP_REQUEST
  • POLICY_LOOKUP_REQUEST
  • POLICY_PAYMENT_REQUEST
• Note that the following ErrorDetail.RequestType enumerated values are deprecated and should not be used:
• TRAFFIC_FINE_PAYMENT_REVERSAL (use PAYMENT_REVERSAL instead)
• TRAFFIC_FINE_PAYMENT_CONFIRMATION (use PAYMENT_CONFIRMATION instead)

v4.1.0 - 11 November 2016

• Added support for Traffic Fine and Policy lookups and payments.
• Account object in responses is now optional.
• Added indicators for allowance of part- and over-payments of accounts etc.
• Added GIFT_CARD and LOYALTY tender types.
• Relaxed restrictions on allowed characters in Originator.terminalId field.
• Included issuerReference as part of basic SlipData and extended length to 40.
• Added basketRef field to indicate related transactions.

v4.0.0 - 27 October 2016

• Formatting included as part of SlipLine entries in BillSlipData field.
• Defined BasicAdviceResponse returned when acknowledging an advice.
• Added request IDs and request type to ErrorDetail responses.
• Amounts are now encapsulated in an Amounts model.

v3.0.3 - 25 August 2016

• Non-functional refactoring.

v3.0.2 - 25 August 2016

• Non-functional refactoring.

v3.0.1 - 22 August 2016

• Non-functional refactoring.

v3.0.0 - 22 August 2016

• Non-functional refactoring.

v2.0.5 - 12 August 2016

• Removed clientRef field from PaymentRequests

v2.0.4 - 10 August 2016

• Added ID number and contact number to customer description.

v2.0.3 - 4 August 2016

• Non-functional refactoring.

v2.0.2 - 4 August 2016

• Non-functional refactoring.

v2.0.1 - 19 July 2016

• Added Account and Customer to basic response to all requests.

v2.0.0 - 13 July 2016

• Non-functional refactoring.

v1.0.0 - 30 June 2016

• Initial release.