mobile money api
API endpoint fields are described in this specification as follows:
→ Request optionality
← Response optionality
O Field is optional
M Field is mandatory
C Field is conditional
NA Field does not need to be supplied. If supplied, it will be ignored.
TIP
Please note that string fields have a default maximum length of 256 characters unless specified otherwise.
The transaction API can be used by FSPs to make a transfer for a linked account. Prior to making the transfer, a link must have been established between the debit and credit accounts.
The following paths are permitted:
| Operation | Path | Description |
|---|---|---|
| Create | POST /transactions/type/{transactiontype} | To be used for transaction creation when the provider’s API Gateway requires that the transaction type be identified in the URL. |
| View | GET /transactions/{transactionReference} | To view a transaction. |
| Update | PATCH /transactions/{transactionReference} | To update the transactionStatus of a transaction. |
| Transaction Object | |||||
|---|---|---|---|---|---|
| Name | Type | Description | Reference | Validation | |
| transactionReference | string | Unique reference for the transaction. This is returned in the response by API provider. | → NA ← M | ||
| requestingOrganisationTransactionReference | string | A reference provided by the requesting organisation that is to be associated with the transaction. | → O ← O | ||
| originalTransactionReference | string | For reversals and refunds, this field indicates the transaction which is the subject of the reversal. | → O ← O | ||
| creditParty | array | A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. | → C ← C | Account Identifiers | creditParty must be supplied if debitParty is omitted. If debitParty is supplied, then creditParty is optional. |
| debitParty | array | A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. | → C ← C | Account Identifiers | debitParty must be supplied if creditParty is omitted. If creditParty is supplied, then debitParty is optional. |
| type | string | The harmonised Transaction Type (not required if passed in the URL) | → M ← M | Enumeration = Transaction Types | |
| subType | string | A non-harmonised sub-classification of the type of transaction. Values are not fixed, and usage will vary according to Provider. | → O ← O | ||
| transactionStatus | string | Indicates the status of the transaction as stored by the API provider. | → NA ← M | ||
| amount | string | The transaction amount. | → M ← M | Please refer to API Fundamentals document for amount validation rules. | |
| currency | string | Currency of the transaction amount. | → M ← M | Enumeration = ISO Currency Codes | |
| descriptionText | string | Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on a notification SMS and on an account statement. | → O ← O | ||
| fees | array | Allows the passing and/or returning of all fees pertaining to the transaction. | → O ← O | Fees Object | |
| geoCode | string | Indicates the geographic location from where the transaction was initiated. | → O ← O | ||
| oneTimeCode | string | A one-time code that can be supplied in the request or can be generated in the response depending upon the use case. An authorisation code can be supplied in this field for requests that have been pre-authorised. | → O ← O | ||
| requestingOrganisation | object | The originating organisation of the request. | → O ← O | Requesting Organisation Object | |
| servicingIdentity | string | The field is used to identify the servicing identity for transactions, e.g. till, POS ID, assistant ID. | → O ← O | ||
| transactionReceipt | string | Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. | → NA ← O | ||
| creationDate | date-time | Date and time when the transaction was created by the API Provider | → NA ← O | ||
| modificationDate | date-time | Date and time when the transaction was modified by the API Provider | → NA ← O | ||
| requestDate | date-time | The creation date and time of the transaction as supplied by the client. | → O ← O | ||
| customData | string | A collection of key/value pairs that can be used for provider specific fields. | → O ← O | Custom Data Object | |
| metadata | array | A collection of key/value pairs. These can be used to populate additional transaction fields. | → O ← O | Metadata |
The Reversals API is used to reverse, adjust or refund a financial transaction. The originating transaction reference must be provided in the path in order to identify the transfer to be reversed. For a partial reversal, the amount needs to be supplied. It should be noted that some API Providers do not support partial reversals and will return an error if a partial amount is supplied.
For viewing reversals, the Transactions API should be used. For performing a reversal without the original transaction reference, use the Transactions API.
The supported path is POST /transactions/{originalTransactionReference}/reversals.
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| transactionReference | string | Unique reference for the transaction. This is returned in the response by API provider. | NA M | ||
| requesting OrganisationTransactionReference | string | A reference provided by the requesting organisation that is to be associated with the transaction. | O O | ||
| originalTransactionReference | string | For reversals and refunds, this field indicates the transaction which is the subject of the reversal. | NA M | ||
| creditParty | array | A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. | O O | Account Identifiers | |
| debitParty | array | A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. | O O | Account Identifiers | |
| type | string | The harmonised Transaction Type | M M | Enumeration = Transaction Types Note that only Reversals and Refunds (adjustments) are supported. | |
| subType | string | A non-harmonised sub-classification of the type of transaction. Values are not fixed, and usage will vary according to Provider. | O O | ||
| transactionStatus | string | Indicates the status of the transaction as stored by the API provider. | NA M | ||
| amount | string | The transaction Amount. | O O | Please refer to API Fundamentals document for amount validation rules. | |
| currency | string | Currency of the transaction amount. | O O | Enumeration = ISO Currency Codes | |
| descriptionText | string | Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on a notification SMS and on an account statement. | O O | ||
| fees | array | Allows the passing and/or returning of all fees pertaining to the transaction. | O O | Fees Object | |
| geoCode | string | Indicates the geographic location from where the transaction was initiated. | O O | ||
| requestingOrganisation | object | The originating organisation of the request. | O O | Requesting Organisation Object | |
| servicingIdentity | string | The field is used to identify the servicing identity for transactions, e.g. till, POS ID, assistant ID. | O O | ||
| transactionReceipt | string | Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. | NA O | ||
| creationDate | date-time | Date and time when the transaction was created by the API Provider. | NA O | ||
| modificationDate | date-time | Date and time when the transaction was modified by the API Provider. | NA O | ||
| requestDate | date-time | The date and time of the transaction request as supplied by the client. | O O | ||
| customData | string | A collection of key/value pairs that can be used for provider specific fields. | O O | Custom Data Object | |
| metadata | array | A collection of key/value pairs. These can be used to populate additional properties that describe administrative information regarding the transaction. | O O | Metadata |
Using the mobile money APIs, financial service providers can:
Two methods are provided for identifying an FSP account, the single identifier method, and the multiple identifiers method.
In the scenario where one identifier suffices to uniquely identify an account, the following path is to be used:
/accounts/{identifierType}/{identifier}.
Where a single identifier is not sufficient to identify an account, the following path is to be used:
/accounts/{accountIdentifier1}@{value1}${accountIdentifier2}@{value2}${accountIdentifier3}@{value3}.
The path uses a $ delimiter to separate each identifier, up to a limit of three account identifiers. Each key/value is delimited by @.
The list of permitted account identifiers supported by the Mobile Money API can be found in the Account Identifiers section.
An FSP should use this API to return a list of transfers against their account. One of the following paths can be used:
GET /accounts/{identifierType}/{identifier}/transactions
or GET /accounts/{Account Identifiers}/transactions
To filter the number of records returned, the following query strings can be used:
| Parameter | Type | Format | Description |
|---|---|---|---|
| limit | integer | N/A | Supports pagination. If this is not supplied, then the server will apply a limit of 50 records returned for each request. |
| offset | integer | N/A | Supports pagination. This value will indicate the cursor position from where to retrieve the set of records. For example, a limit of 50 and offset of 10 will return records 11 to 60. |
| fromDateTime | string | date-time | Indicates the minimum date creationDate for which records should be returned. |
| toDateTime | string | date-time | Indicates the maximum date creationDate for which records should be returned. |
| transactionStatus | string | N/A | Indicates the status of the transactions to be returned. |
| transactionType | string | N/A | Indicates the type of the transactions to be returned. |
Note 1:
For a harmonised behavior, API Providers should make sure that the transactions are returned in descending date created order.
Note 2:
HTTP response headers are returned with each response indicating the total number of records available (X-Records-Available-Count) and total number of records returned (X-Records-Returned-Count).
Figure 2‑3 Account Transaction UML Class Diagram
Using the Account Balances API, an FSP can check their balance. Permitted paths are:
GET /accounts/{identifierType}/{identifier}/balance
or GET /accounts/{Account Identifiers}/balance
A ‘self’ version is also available where the calling API client is the FSP account holder. Path for the ‘self’ version is /accounts/balance.
Figure 2‑4 Account Balance UML Class Diagram
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| accountStatus | string | Indicates a harmonised representation of the account state. This will be shown as ‘available’ or ‘unavailable’. A state of ‘unavailable’ means that the account is in a state that does not allow posting of transactions. Unregistered indicates that although not available, a transaction created with the account identifier(s) will result in an unregistered voucher creation. | NA O | Enumeration = available, unavailable, unregistered | |
| currentBalance | string | The current outstanding balance on the account. | NA O | Please refer to API Fundamentals document for amount validation rules. | |
| availableBalance | string | Indicates the balance that is able to be debited for an account. This balance is only provided on some API provider systems. | NA O | Please refer to API Fundamentals document for amount validation rules. | |
| reservedBalance | string | Indicates the portion of the balance that is reserved, i.e. intended to be debited. This balance is only provided on some API provider systems. | NA O | Please refer to API Fundamentals document for amount validation rules. | |
| unClearedBalance | string | Indicates the sum of uncleared funds in an account, i.e. those that are awaiting a credit confirmation. | NA O | Please refer to API Fundamentals document for amount validation rules. | |
| currency | string | Currency for all returned balances. | NA O | Enumeration = ISO Currency Codes |
The Links APIs are used to establish a link between two separate accounts between financial service providers. The API can be used for example to link a mobile wallet account to a microfinance institution account or a bank account. The link object does not mandate the processes to verify and authenticate a link request - this depends upon the use case. A link needs to be associated with a mode of operation:
pull. The link can be used by the client to debit the target account held by the provider.
push. The link can be used by the client to credit the target account held by the provider.
both. The link can be used for Push and Pull requests.
To identify the accounts that are to be linked, the target account is specified in the path whereas the source account is specified in the link object.
The permitted paths are as follows:
Creation: POST /accounts/{identifierType}/{identifier}/links or POST /accounts/{ Account Identifiers}/links.
Update of status and/or mode fields: PATCH /accounts/{identifierType}/{identifier}/links/{linkReference} or PATCH /accounts/{Account Identifiers}/links/{linkReference}.
Read. GET /accounts/{identifierType}/{identifier}/links/{linkReference} or GET /accounts/{Account Identifiers}/links/{linkReference}.
Synchronous and asynchronous modes are supported for POST and PATCH methods whereas only synchronous mode is supported for the GET method.
Figure 2-5 Link UML Class Diagram
| Link Object | |||||
|---|---|---|---|---|---|
| Name | Type | Description | Reference | Validation | |
| linkReference | string | Indicates the Link reference. This enables a linked account to be uniquely identified. | → NA ← M | ||
| sourceAccountIdentifiers | array | A series of key/value pairs that identify the source account. Keys include MSISDN and Wallet Identifier. | → M ← M | Account Identifiers | |
| mode | string | Indicates the mode of operation for the Link. | → M ← M | Enumeration = push, pull, both | |
| status | string | Indicates the status of the Link. | → M ← M | Enumeration = active, inactive | |
| requestingOrganisation | object | The originating organisation of the request. | → O ← O | Requesting Organisation | |
| creationDate | date-time | Indicates when the link was created as recorded by the API provider. | → NA ← O | ||
| modificationDate | date-time | Indicates when the link was modified as recorded by the API provider. | → NA ← O | ||
| requestDate | date-time | The date and time of the link request as supplied by the client. | → O ← O | ||
| customData | string | Contains provider specific fields. | → O ← O | Custom Data Object |
The Account Identifier object enables one or multiple identifiers to be provided to enable the recipient system to resolve the account/party.
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| key | string | Provides the account identifier type. | M M | Enumeration = Account Identifiers | |
| value | string | Provides the account identifier type value. | M M |
The metadata object allows fields to be specified to convey administrative information regarding the associated resource in the form of key/value pairs. Additional fields should only be used where no suitable defined field match can be found. The number of key/value pairs is limited to 20.
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| key | string | Identifies the type of additional fields. | M M | ||
| value | string | Identifies the value of the additional field. | M M |
The custom data object allows additional fields to be specified for the associated resource in the form of key/value pairs. Additional fields should only be used where no suitable defined field match can be found. The number of key/value pairs is limited to 20.
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| key | string | Identifies the type of additional fields. | M M | ||
| value | string | Identifies the value of the additional field. | M M |
An object that enables fees that are differentiated by type to be provided and/or returned.
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| feeType | string | Defines the type of fee. | M M | ||
| feeAmount | string | Defines the amount of the fee. | M M | Please refer to API Fundamentals document for amount validation rules. | |
| feeCurrency | string | Defines the currency for the given fee. | M M | Enumeration = ISO Currency Codes |
An object that details the originating organisation of the request.
| Name | Type | Description | Reference | Validation | |
|---|---|---|---|---|---|
| requestingOrganisationIdentifierType | string | Identifies the identifier type of the requesting organisation. | → M ← M | ‘swiftbic’, ‘lei’, ‘organisationid | |
| requestingOrganisationIdentifier | string | Contains the requesting organisation identifier. | → M ← M |
The three-character alphabetic code for currency as defined by ISO 4217 is to be used for all currency fields. The full list of codes is maintained by Swiss Interbank Clearing on behalf of the International Organisation for Standardisation. This list can be obtained via the following website - http://www.currency-iso.org/en/home/tables/table-a1.html (opens new window).
A transaction type is used to classify the nature of a transaction.
| Code | Description |
|---|---|
| transfer | Transfer of funds between mobile money provider and another provider or financial institution in the same country. |
| reversal | Reversal of a prior transaction to return funds to the payer. |
The Account Identifier enumeration lists all possible means to identify a target account. Identifiers can be combined if necessary, to provide a unique identifier for the target account.
| Code | Short Description | Type | Description |
|---|---|---|---|
| accountcategory | Account Category | string | Can be used to identify the sources of funds category where there are multiple accounts (wallets) held against an account holder. |
| bankaccountno | Bank Account Number | string | Financial institution account number that is typically known by the account holder. |
| accountrank | Account Rank | string | Is used to identify the rank of the source of funds where there are multiple accounts (wallets) held against an account holder. |
| identityalias | Identity Alias | string | An alias for the identity, e.g. short code for an agent till. |
| iban | IBAN | string | Internationally agreed system of identifying bank accounts across national borders to facilitate the communication and processing of cross border transactions. Can contain up to 34 alphanumeric characters. |
| accountid | Account Holder Identity | string | Identifier for the account holder. |
| msisdn | MSISDN | string | Must contain between 6 and 15 consecutive digits First character can contain a ‘+’ or digit Can contain spaces. |
| swiftbic | SWIFTBIC | string | A bank identifier code (BIC) is a unique identifier for a specific financial institution. A BIC is composed of a 4-character bank code, a 2-character country code, a 2-character location code and an optional 3-character branch code. BICs are used by financial institutions for letters of credit, payments and securities transactions and other business messages between banks. Please refer to ISO 9362 (opens new window) for further information. |
| sortcode | Bank Sort Code | string | Sort code to identify the financial institution holding the account. |
| organisationid | Organisation Account Identifier | string | Used to identify the organisation for which a payment is to be made. |
| username | Username | string | Used to identify target account via an associated username. |
| walletid | Wallet Identifier | string | A means to identify a mobile money wallet, particularly where multiple wallets can be held against an MSISDN. typically used in conjunction with MSISDN or identity alias to identify a particular wallet. |
| linkref | Link Reference | string | A means to uniquely identify an account via an account to account link. E.g. wallet account link to bank account. |
| consumerno | Consumer Number | String | Identifies the consumer associated with the account. |
| serviceprovider | Service Provider | String | Provides a reference for a Service Provider. |
| storeid | Store ID | String | Identifies the transacting store / retail outlet. |
| bankname | Bank Name | String | Name of the bank. |
| bankaccounttitle | Bank Account Title | String | The title of the bank account. |
| emailaddress | Email Address | String | emailaddress of the party. |
| mandatereference | Debit Mandate Reference | String | A means to identify an account via a debit mandate reference. |