^

API Fundamentals

URI

All services exposed by the harmonised Mobile Money API use the following URI format:

{…}/{version}/mm/{Resource}

Where:

  • is defined upon implementation of the API by the API provider.
  • version is as per standards defined in the API Versioning section.
  • mm is literal for ‘Mobile Money’
  • resource identifies the object and resource that is the subject of the API.


Operations

The API supports three types of operations, each represented by HTTP Verb as shown below:

  • POST. Used to create a resource for a given resource type. Transactions, Quotations and Debit Mandates can be created using the API.
  • PATCH. Used to update a resource for a given resource type. Debit Mandates and Links can be updated using the API. But note that only specific properties can be updated – refer to the relevant API service for more information.
  • GET. Used to return a representation(s) of a resource(s) or collection of resources. All resources support GET operations.


Patch Specifics

Updates to resources are accomplished by use of the HTTP PATCH operation. The proposed PATCH format is based upon IETF RFC 6902. One specific operation is supported:

  • Replace. This operation replaces the value of the target property with the supplied value. An example of a replace operation is:

    [{ "op": "replace", "path": "/XYZ", "value": test }]
    where XYZ is the target property.



Resource Naming

The format of the resource part of the URI identifies the type of resource and if applicable, the specific resource for which an operation is to be performed. Resources are always reflected in plural and by use of nouns. Primary URI constructs for the API are as follows:

  • /transactions. Identifies a transaction resource.
  • /accounts. Identifies the financial resource that holds the funds. Examples include bank accounts and mobile wallets.
  • /quotations. The resource that holds the quote or quotes for international remittance quotations.
  • /statemententries. The resource that returns an account statement representation. This is typically qualified by /accounts but can be used in isolation to return a specific statement entry if the transaction reference is known.
  • /accounts/debitmandates. The resource that holds the debit mandate instructions, i.e. mandates that allow a Payee to deduct funds from a Payers account.
  • /accounts/links. Represents an account to account link between two systems. Note that links are qualified by Accounts for creation requests.
  • /accounts/bills. Represents a bill that is due to be paid or has been paid.
  • /accounts/accountname. Represents the primary account holders name.
  • /accounts/balance. Represents the balance(s) associated with an account.
  • /accounts/status. Represents that ability of the account to receive/send funds.
  • /batchtransactions. Represents a collection of transactions and related batch metadata.

A more exhaustive list of permitted resources and permitted resource hierarchies can be found in the detailed sections of this site.



Identifying the Resource

The harmonised Mobile Money API has adopted a RESTful approach to identifying the resource on which an operation is to be performed. Where possible, the identifier is specified following the resource name in the URI. In some cases, more than one identifier is required to identify the resource or there is a choice on which identifier to use. So some flexibility has been built into the URI to cater for these cases. This is illustrated in the following table.

Resource Operation Identifier Identifier Placement
Transactions GET Transaction Reference URI
Accounts GET Various Account Identifiers (see Accounts for details) URI
Mandates PATCH and GET Mandate Reference URI
Quotations PATCH and GET Quotation Reference URI
StatementEntries GET None if qualified by Accounts. If individual entry, then use Transaction Reference URI
Links PATCH and GET Link Reference URI
Bills GET Account Identifiers URI
Bill Payments POST Bill Payment Reference and Account Identifiers URI
BatchTransactions PATCH and GET Batch Reference URI


Client Correlation ID

A Client Correlation ID is to be supplied by the API client on HTTP POST and PATCH requests. Put simply, the Client Correlation ID is a unique identifier that enables the client to correlate the API request with the resource created/updated by the provider. The client correlation ID is captured in the HTTP Header.

The format for the correlation ID is a GUID. Critically, the correlation ID supports safe operations. A POST request that is submitted with a correlation that has already been supplied will be rejected as unsafe, thus avoiding transaction duplication.



Use Case Flow Patterns

All Use Cases supported by the API are built on standard flow patterns. Flow patterns exist for viewing, creating and updating records (resources). Flow patterns can be combined in a single use case. For example, a domestic transfer may involve a name check on the recipient platform prior to a request to create a transaction. There are some simple rules to follow when using flow patterns. These are illustrated below:

  • Viewing. Only synchronous flows are supported for viewing resource(s). For example, a HTTP GET request to view balances must result in a HTTP response yielding the representation of the resource or representation of the error.
  • Creating/Updating. Synchronous and asynchronous flows are supported. A synchronous flow involves a definitive result (resource representation or error representation returned) being provided in the HTTP POST response. An asynchronous flow is supported by two mechanisms – Callback and Polling. These are described in more detail in the Request State Object section.


Case Sensitivity

All enumeration values referenced within the API use lower case notation – this includes acronyms and abbreviations. The only exceptions are for ISO Codes (country and currency) – the API uses these codes as defined per ISO.

In this document properties are split into words with the first character capitalised for readability. However, the API properties in the actual API (Swagger definition) use camelCase format.



HTTP Header Information

The following header information can be supplied for the mobile money API.

HTTP Request Headers

Header Value Optionality Notes
Accept application/json Mandatory  
Accept-Charset utf8    
Authorization Authorization: Basic {base64Encode(concatenated client's username and password)} See notes Mandatory unless OAuth2 scheme is used
Content-Length {length of request content in 8-bit bytes} Mandatory  
Content-Type application/json Mandatory  
Date {The date and time that the message was originated in HTTP-date format - RFC 7231} Mandatory  

HTTP Response Headers

Header Value Optionality Notes
Content-Length {length of response content in 8-bit bytes} Conditional Applicable only if the HTTP response contains JSON body
Content-Type application/json; charset=utf-8 Conditional Applicable only if the HTTP response contains JSON body
Date {The date and time that the message was sent in HTTP-date format - RFC 7231} Mandatory Mandatory unless OAuth2 scheme is used

Custom Headers

Header Value Optionality Notes
X-API-Key* Used to pass pre-shared client's API key to the server Mandatory  
X-Client-ID* Used to pass pre-shared client's identifier to the server Mandatory  
X-Content-Hash* SHA-256 hex digest of the request content (encrypted or plain) Conditional Applicable only if the HTTP request contains JSON body
X-Correlation-ID GUID Mandatory See Client Correlation ID
X-Records-Available-Count Integer containing number of records that are available to be returned Conditional Used in the event of pagination
X-Records-Returned-Count Integer containing the number of records that have been returned Conditional Used in the event of pagination

*Please refer to the Mobile Money API Design for further information.




API Versioning

When changes are made to the Mobile Money API, a new version is released. There are two types of API versions – minor (backwards compatible) and major (backwards-incompatible) versions.

The following types of changes are considered to be backwards compatible and hence minor:

  • Addition of new API Services.
  • Adding optional request properties and/or optional input parameters such as query strings to existing objects.
  • Addition of new properties to existing API responses.
  • Changing the order of properties within a request or response object.
  • New error codes.

The following types of changes are considered to be backwards incompatible and hence major:

  • Introducing mandatory properties.
  • Changing datatypes on properties.
  • Changes to API URIs.

The version that a client intends to use is indicated URI. Format is ‘X.Y’ where ‘X’ is the major version and ‘Y’ is the minor version. Both versions are sequentially numbered. Note that when a major version is incremented, the minor version is reset to zero. The initial released version of the API is 1.0.

There are many different mobile money and third party providers and hence clients connecting to multiple providers are likely to interact with different versions of the API. Client code developed against an older minor version on one client will work on all newer minor versions existing on other clients. However, client code developed against a new minor version will not necessarily work against older minor versions.