Upgrade to OAS version 3

Mobile Money API version 1.1 has been developed using OAS version 3 to take advantage of the new modelling and schema reuse capabilities that OAS3 provides. This has led to significant reuse of schemas/properties and has significantly improved readability.

 

Overhaul of Callback mechanism

In version 1.0 of the mobile money API, callbacks were issued via a patch command with clients unable to specify a URL to receive the callback. In version 1.1, the following improvements have been made:
o The client can specify full callback URL using a new request header X-Callback-URL.
o A full representation of the created resource is sent back (via PUT) in response to a successful creation request.
o Mobile Money API callbacks have been modelled using callback operations introduced in OAS v3.
The new mechanism is illustrated as follows:

 

Improved implementation of identifier types in path

The Mobile Money API now permits any Identifier Type in path, not just MSISDN:
o Original version 1.0 implementation: /accounts/msisdn/{msisdn}/
o New version 1.1 implementation: /accounts/{identifierType/{identifier}/

 

New APIs for Bill Companies

New set of APIs to enable clients to retrieve Bill Company information.

 

New Authorisation Codes APIs

Provide the ability to generate & cancel transaction authorisation codes which can expire.
Provides support for ATM withdrawals & voucher code-based transactions.

 

New API - POST /transactions/type/{transactionType]

Enables the transaction type to be identified in the URL when creating a transaction.
This is required in some API Gateway implementations to allow fine grained API permissions to be applied.

 

Account Balance ‘Self’ API

Added new ‘self’ API for account balance, removing the need for the account subject to identify itself in the path.

 

Additional Identifier Types

Added new identifier types in version 1.1:
o serviceprovider
o storeid
o bankname
o bankaccounttitle
o emailaddress
o mandatereference

 

Alignment of Headers with Security Specification

Ensured that all customer headers identified in the security specification are reflected in the main API specification.

 

Implemented optionality on some custom headers.

Following feedback from implementers, the following custom headers were changed from mandatory to optional:
o X-Date. Note that this also involved a name change from Date to X-Date as Date is a reserved keyword in many implementations.
o X-CorrelationID

 

Bills API Improvements

Added billStatus property.

 

Transaction and Quotation Fees

Passing of fees are now supported on transactions and quotations APIs.

 

Transaction Filters

Added status and type as query string parameters to enabling improved filtering for transaction retrieval.

 

Quotations for Domestic Remittance

Added ability to obtain quotations for domestic remittances.

 

New Custom Headers for request routing

Added new routing request headers to allow the ultimate account holding institution to be identified through an LEI code, Swift-BIC code or Organisation Id.

 

Improved Regular Expression for amount validation

Implemented new regular expression for amount properties to support a move towards implementing a canonical number format for amounts.

 

Forex Rate optionality

Forex rate changed from mandatory to optional.
Increased the property from 2 to 10 decimal places.

 

Mobile Number Validation

Local and international formats now supported via modified regular expression.

 

Property Alignment between OAS Specification and the Human-readable Specification

Fixed a number of minor misalignments between the two specifications.

 

Bill Payments additional properties

Added the following properties to Bill Payments API:
o serviceProviderPaymentReference
o billPaymentStatus
o requestingOrganisationTransactionReference
o requestingOrganisation
o metadata
o serviceProviderComment
o serviceProviderNotification

 

Batch Transactions API Record Limit

Applied limit of one million transactions for Batch Transactions API.

 

General Property Optionality Changes

Changed a number of properties from Mandatory to Optional or N/A in response to review feedback.

 

Credit and Debit Party Conditionality

Allow optional implicit identification of one or other party