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.
API Behaviour & Error Handling
Overview
The ability to manage API state and handle exceptions in a consistent manner is central to the harmonised Mobile Money API. Consistency is achieved via the following:
- Harmonised API State Model. For synchronous requests, HTTP response codes are used exclusively to manage request state communication – both during the creation of a resource and updating of a resource. For asynchronous requests, a simple RequestState object is additionally used to manage request state communication.
- Harmonised HTTP Status Codes. Standardised HTTP status codes are associated with a harmonised state model for resource creation and update.
- Harmonised Application-level Error Reason Codes. Standardised error codes are returned in a standardised error object for ALL client-responsible and server-responsible errors. Error parameters allow more detailed provider-specific diagnostic information to be returned with the error.
- API Heartbeat enables API provider service availability to be established by clients on a regular basis.
- Responses object enables clients to re-request a missing API response.
- Error Handling Guidelines provide a standardised way of handling exceptions, including managing timeouts and retries.
Request State Object
Asynchronous flows involve either a callback or a polling mechanism to enable to client to determine the final state of the request. Both mechanisms involve the use of the RequestState object as per below:
- Callback. A request is initiated via a HTTP POST or PATCH request with an intermediate response represented by a RequestState object. Once the request has been completed, the provider will initiate a PATCH request to provide the client with the final RequestState.
- Polling. Is initiated by a HTTP POST or PATCH request with an intermediate response provided in the form of the RequestState object. A HTTP GET is then issued on the RequestState by the client at regular defined intervals until the final resource state is returned.
The object definition for RequestState is described below.
Name | Type | Description | Request | Response | Reference | Validation |
---|---|---|---|---|---|---|
Server Correlation ID | String | A unique identifier issued by the provider to enable the client to identify the RequestState resource on subsequent polling requests. | NA | Mandatory | GUID | |
Status | String | Indicates the status of the request. | NA | Mandatory | Enumeration = pending, completed, failed | |
Pending Reason | String | A textual description that can be provided to describe the reason for a pending status. | NA | Optional | ||
Notification Method | DateTime | Indicates whether a callback will be issued or whether the client will need to poll. | NA | Mandatory | Enumeration = callback, polling | |
Object Reference | Reference | Provides a reference to the subject resource, e.g. transaction reference. | NA | Optional | ||
Expiry Time | DateTime | Indicate the time by which the provider will fail the request if completion criteria have not been met. For an example, a debit party failing to authorise within the allowed time period. | NA | Optional | ||
Poll Limit | Integer | Indicates the number of poll attempts for the given requeststate resource that will be allowed by the provider. | NA | Optional | ||
ErrorReference | Reference | If the asynchronous processing failed, details of the error will be returned here | NA | Optional | Errors Object | |
API Behavioural Model
Overview
API behaviour is governed by the following factors:
- The resource.
- The type of operation, i.e. create, update or read.
- Whether the provider will process the request synchronously.
- Whether the provider implements callback or polling methods for asynchronous processing.
When combined, these factors drive API behaviour from the simplest request (e.g. view an account balance) to a more complex request (e.g. update a debit mandate asynchronously).
Request State Object
Asynchronous flows involve either a callback or a polling mechanism to enable to client to determine the final state of the request. Both mechanisms involve the use of the RequestState object as per below:
- Callback. A request is initiated via a HTTP POST or PATCH request with an intermediate response represented by a RequestState object. Once the request has been completed, the provider will initiate a PATCH request to provide the client with the final RequestState.
- Polling. Is initiated by a HTTP POST or PATCH request with an intermediate response provided in the form of the RequestState object. A HTTP GET is then issued on the RequestState by the client at regular defined intervals until the final resource state is returned.
The object definition for RequestState is described below.
Name | Type | Description | Request | Response | Reference | Validation |
---|---|---|---|---|---|---|
Server Correlation ID | String | A unique identifier issued by the provider to enable the client to identify the RequestState resource on subsequent polling requests. | NA | Mandatory | GUID | |
Status | String | Indicates the status of the request. | NA | Mandatory | Enumeration = pending, completed, failed | |
Pending Reason | String | A textual description that can be provided to describe the reason for a pending status. | NA | Optional | ||
Notification Method | DateTime | Indicates whether a callback will be issued or whether the client will need to poll. | NA | Mandatory | Enumeration = callback, polling | |
Object Reference | Reference | Provides a reference to the subject resource, e.g. transaction reference. | NA | Optional | ||
Expiry Time | DateTime | Indicate the time by which the provider will fail the request if completion criteria have not been met. For an example, a debit party failing to authorise within the allowed time period. | NA | Optional | ||
Poll Limit | Integer | Indicates the number of poll attempts for the given requeststate resource that will be allowed by the provider. | NA | Optional | ||
ErrorReference | Reference | If the asynchronous processing failed, details of the error will be returned here | NA | Optional | Errors Object | |
Sequence Flows
There are seven sequence flows that can be implemented over the mobile money API. These are reflected in the attached sheet below. The sheet indicates the necessary HTTP operations, request object, response object and expected success and failure response codes for each API service.
Mobile Money API Request Response [13kb]
API Flow Patterns
Sequence diagrams 2 through 8 illustrate the standard flow patterns for the mobile money API. Note that Green flows represent a success path and red flows represent a failure path. A solid line indicates a HTTP request and a dotted line indicates a HTTP response.
Figure 2: Read (GET) Flow Pattern
Figure 3: Create (POST) Synchronous Flow Pattern
Figure 4: Create (POST) Callback Asynchronous Flow Pattern
Figure 5: Create (POST) Polling Asynchronous Flow Pattern
Figure 6: Update (PATCH) Synchronous Flow Pattern
Figure 7: Update (PATCH) Callback Asynchronous Flow Pattern
Figure 8: Update (PATCH) Polling Asynchronous Flow Pattern
HTTP Status Responses and Error Categories
Overview.
At a high-level, the following HTTP status codes are returned for operations:
Operation | Success | Intermediate* | Client Error | Server Error |
---|---|---|---|---|
GET | 200 | N/A | 400, 401, 404 | 500, 503 |
PATCH | 204 | 202 | 400, 401, 404 | 500, 503 |
POST | 201 | 202 | 400, 401, 404 | 500, 503 |
*Note that ‘intermediate’ in the table above relates to the HTTP response for the first leg of an asynchronous request.
Client Error Categories
Client errors fall into one of four categories as shown below:
Error Category | Description | HTTP Response Code |
---|---|---|
BusinessRule | The resource could not be successfully completed due a violation of a business rule. Business rules include financial limit violations, duplicate requests and invalid states. | 400 |
Validation | Violation of a constraint that will prevent the resource from being processed. Examples include:
|
400 |
Authorisation | It was not possible to authenticate or authorise the client or other party to perform the service | 401 |
Identification | The requested resource could not be matched on the system with the supplied identifier(s). | 404 |
Additional non-harmonised 4xx HTTP response codes may be returned to the client by web or proxy servers.
Where the need for prevention of information leakage is paramount and this outweighs the benefits of error granularity, the provider may wish to use a 400 response code with no error body.
Server Error Categories
Server Errors are captured in two simple categories as per the following table:
Error Category | Description | HTTP Response Code |
---|---|---|
Internal | The request could not be completed due to a non-client related issues that do not constitute complete system unavailability. Examples include software licence issues, unavailability of system configuration information. | 500 |
Service Unavailable | The service is not currently available. This could be due to network issues, issues with individual components or complete systems outages. Regardless of the cause, the result means that the request cannot be performed. | 503 |
Additional non-harmonised 5xx HTTP response codes may be returned to the client by web or proxy servers.
Error Codes Definition
Overview
The mobile money API uses harmonised error codes in order to provide consistent error reporting back to API clients. Error codes are structured as per follows
- Error Category. All error codes must be associated with a client or server error category. This provides context and uniqueness to the error code.
- Error Code. Provides the reason for the request failure. A human-readable description of the error is also available. Error codes are generally granular, i.e. the provide a specific reason for failure. In some cases, granularity is neither possible or desirable. Where this is the case, a ‘Generic’ code has been defined. Cases include:
- The API Provider has generated an error that does not map to existing Rule error codes.
- The API Provider wishes to avoid disclosure of confidential information regarding the resource or parties to the resource. For example, the fact that a customer has breached their monthly transaction limit may not be disclosed to specific clients.
- Error Parameters. Provides a construct to communicate supplementary information regarding the error in key/value pairs. The supplementary information is currently non-harmonised and can include:
- The API provider-specific Error Code and Description
- Additional identification of the error subject, e.g. account identifiers, invalid properties etc…
- Diagnostic information, e.g. affected subsystem, licence failure type etc…
- Note that although error parameter contents are non-harmonised, care should be taken regarding confidentially of disclosed information. Confidential parameter information should only be disclosed to trusted clients.
A full list of harmonised Error Codes is provided in the Harmonised Error Codes section
Errors Object Definition
Overview
All errors generated by the API provider will contain an Errors object in the response body. At a minimum, the Errors object must contain the Error Reason and Error Code.
Name | Type | Description | Request | Response | Reference | Validation |
---|---|---|---|---|---|---|
Error Category | String | The category grouping for the error. | Mandatory | Mandatory | Enumeration = Error Categories | |
Error Code | String | The harmonised error code identifying the reason for error. | Mandatory | Mandatory | Enumeration = Error Reasons | |
Error Description | String | A textual Description of the error. | Optional | Optional | ||
Error DateTime | DateTime | The timestamp indicating when the error occurred. | Optional | Optional | ||
Error Parameters | Reference | Diagnostic information in the form of key/value pairs relating to the error. | Optional | Optional | Metadata |
Missing Response Retrieval
Overview
In some circumstances, the client may not have received the final representation of the resource for which it attempted to create. For example, a proxy server issue may have resulted in a HTTP 5xx response but the provider may have actually successfully completed the request. The /Responses API allows a client to identify and retrieve the final representation of the resource assuming that the resource was created. In order to get a representation, the client issues a GET /Responses/{Client Correlation ID}. The provider will then match the client correlation ID to the appropriate resource and return a link to that resource. If the resource is not found for the given correlation ID then a HTTP 404 will be returned.
The response object for /responses is detailed below:
Name | Type | Description | Request | Response |
---|---|---|---|---|
Link | String | Provides a URL to the resource associated with the given correlation ID | NA | Mandatory |
Harmonised Error Codes
Overview
Error Category | Error Code | Error Code Description |
---|---|---|
BusinessRule | GenericError | A generic Error Code for the Rule Error Category. This is used in two scenarios:
|
BusinessRule | DailyVolumeLimitExceeded | The party has exceeded their daily transacting volume limit - This can be a service limit or a limit that is specific to the party. |
BusinessRule | DailyValueLimitExceeded | The party has exceeded their daily transacting value limit - This can be a service limit or a limit that is specific to the party. |
BusinessRule | WeeklyVolumeLimitExceeded | The party has exceeded their weekly transacting volume limit - This can be a service limit or a limit that is specific to the party. |
BusinessRule | WeeklyValueLimitExceeded | The party has exceeded their weekly transacting value limit - This can be a service limit or a limit that is specific to the party. |
BusinessRule | MonthlyVolumeLimitExceeded | The party has exceeded their monthly transacting volume limit - This can be a service limit or a limit that is specific to the party. |
BusinessRule | MonthlyValueLimitExceeded | The party has exceeded their monthly transacting value limit - This can be a service limit or a limit that is specific to the party. |
BusinessRule | AccountMaxTotalValueExceeded | The party has exceeded their cumulative transacting value limit defined for the account. |
BusinessRule | AccountMaxTotalVolumeExceeded | The party has exceeded their cumulative transacting volume limit defined for the account. |
BusinessRule | LessThanTransactionMinValue | The amount specified for the transaction is less than the defined minimum for the service. |
BusinessRule | GreaterThanTransactionMaxValue | The amount specified for the transaction is greater than the defined maximum for the service. |
BusinessRule | MaxBalanceExceed | The amount specified will cause the balance of the credit parties account to exceed the rule limit. |
BusinessRule | SamePartiesError | The debit and credit parties are the same. |
BusinessRule | DuplicateRequest | The request has previously been processed, i.e. this request is a duplicate and hence has been rejected. |
BusinessRule | InsufficientFunds | Available funds are not sufficient to enable the party to be debited for the requested transaction. |
BusinessRule | IncorrectState | The account is in a state that does not permit the requested service. |
BusinessRule | UnderPaymentNotAllowed | The requested amount is less than the amount that needs to be supplied for this transaction |
BusinessRule | OverPaymentNotAllowed | The requested amount is greater than the amount that needs to be supplied for this transaction |
BusinessRule | RateLimitError | The client has submitted too many requests within a period of time. |
BusinessRule | TransactionTypeError | The harmonised transaction type is not supported by the API Provider for the given request. |
BusinessRule | NoMandateAuthority | The transaction request is not supported by the debit mandate. |
BusinessRule | LinkViolation | The request has violated an account to account link for one of the following reasons:
|
BusinessRule | CountryofOriginNotPermitted | The API Provider does not allow transactions to be accepted from the specified country of origin. |
BusinessRule | NationalityNotPermitted | The API Provider does not allow transactions to be accepted from individuals with the specified nationality. |
BusinessRule | IdDocumentNotSupported | The API Provider does not allow the specified ID Document. |
BusinessRule | IssuingCountryNotSupported | The API Provider does not allow the issuing country of the specified ID document. |
QuoteExpiry | QuoteHasExpired | A transaction with a quote reference cannot be processed at the quote has expired. |
Identification | IdentifierError | The requested resource could not be matched on the system with the supplied identifier(s). |
Validation | GenericError | A generic Error Code for the Validation Error Category. This is used in where the API Provider has generated an error that does not map to existing Validation error codes. |
Validation | LengthError | The specified property contents are greater than the maximum allowed length or less than the minimum allowed length. |
Validation | FormatError | The specified property contents do not conform to the format required for this Property. |
Validation | NegativeValue | The amount supplied is negative and this is not allowed for the given service. |
Validation | CurrencyNotSupported | The currency supplied is not supported by the API Provider. |
Validation | MandatoryValueNotSupplied | A mandatory value has not been provided in the header and/or JSON body. |
Validation | InvalidOffset | The pagination offset provided is not valid. This is typically because the offset is greater than the maximum number of records. |
Authorisation | ClientAuthorisationError | General Client Authentication failure. No further details provided to prevent leakage of security information. |
Authorisation | RequestDeclined | The debit party did not approve the request. |
Authorisation | ServicingPartyAuthorisationError | The servicing party (e.g. agent) credentials or permissions are not valid. |
Authorisation | RequestingPartyAuthorisationError | The party requesting the service has not provided the right credentials and/or does not have permission to perform this service. |
Internal | GenericError | The request could not be completed due to a non-client related issues that do not constitute complete system unavailability. Examples include software licence issues, unavailability of system configuration information. |
Service Unavailable | GenericError | The service is not currently available. This could be due to network issues, issues with individual components or complete systems outages. Regardless of the cause, the result means that the request cannot be performed. |
API Heartbeat
Overview
The Heartbeat API is used for monitoring purposes and establishes whether an API provider’s system is in a state that enables a client to submit a request for processing within established SLAs. There are three states that can be returned by the API provider in response to a heartbeat request:
- Available. The system is available and can receive and complete requests within SLAs.
- Degraded. The system can receive and complete requests but not within SLAs, i.e. delay in transaction processing is anticipated. When known, the expected processing delay time can be returned by the provider.
- Unavailable. The system cannot receive and process requests. Any submitted requests will fail whilst the system is in this state.
The Heartbeat can be requested using the following format:
- /heartbeat. Issues heartbeat to determine availability of the transactions service, for example International Transfers.
Only synchronous API Heartbeat requests are supported. Note that the HTTP Request does not contain a request body. The HTTP response contains the following properties.
Name | Type | Description | Request | Response | Validation |
---|---|---|---|---|---|
Service Status | String | Provides the status of the requested service. | NA | Mandatory | Enumeration = available, unavailable, degraded |
Delay | Number | The anticipated processing delay in milliseconds | NA | Optional | Service Status must be set to degraded. |
Planned Restoration Time | Datetime | Where the planned restoration time is known (e.g. scheduled maintenance), it can be provided in this property | NA | Optional |
Supporting Objects
Metadata
Metadata
The metadata object allows additional properties to be specified for the parent object in the form of key/value pairs. Additional properties should only be used where no suitable defined property match can be found. The number of key/value pairs is limited to 20.
Name | Type | Description | Request | Response |
---|---|---|---|---|
Key | String | Identifies the type of additional property. | Mandatory | Mandatory |
Value | String | Identifies the value of the additional property. | Mandatory | Mandatory |