API Service Definition
All Mobile Money API Services and related objects are detailed within the API Service Definition and Supporting Objects sections. The relationships between objects is illustrated in figure 1.
Note: That green represents objects that are directly exposed by an API service and blue represents objects that are referenced by directly exposed objects.
-
. API Object Relationships
Object properties are described in this specification as follows:
-
The property name.
-
The property type.
-
Description of the property.
-
Optionality of the property, i.e. whether the property must be supplied. Optionality is identified as per follows:
🡪 Request optionality
🡨 Response optionality
O Property is optional
M Property is mandatory
C Property is conditional
NA Property does not need to be supplied. If supplied, it will be ignored.
-
Reference where the property is a collection/array and is defined by another object.
-
Validation applied to the property, including enumeration, property length and use of regular expressions to validate format.
Note: All string properties have a default maximum length of 256 characters unless specified otherwise.
Transactions API
The Transactions APIs are used to support mobile money financial transaction use cases. Transactions are used for a wide range of use cases including merchant payments, international transfers, domestic transfers and agent cash-in/cash-out. Reversals and adjustments are also treated as transactions.
The following paths are permitted:
-
POST /transactions. For transaction creation.
-
POST /transactions/type/{transactiontype}. To be used for transaction creation when the provider’s API Gateway requires that the transaction type is identified in the URL. When this path is used, the Transaction Type does not need to be supplied in the request body.
-
GET /transactions/{transactionReference}. To view a specific transaction.
The object definition for Transactions is provided below:
Transaction Base Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
amount |
string |
The transaction amount. |
🡪M 🡨M |
Please refer to Amount Validation |
|
currency |
string |
Currency of the transaction amount. |
🡪M 🡨M |
Enumeration = ISO Currency Codes |
|
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 |
||
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 |
||
requestDate |
date-time |
The creation date and time of the transaction as supplied by the client. |
🡪O 🡨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 |
||
transactionReference |
string |
Unique reference for the transaction. This is returned in the response by API provider. |
🡪NA 🡨M |
||
transactionReceipt |
string |
Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. |
🡪NA 🡨O |
||
requestingOrganisation |
string |
A reference provided by the requesting organisation that is to be associated with the transaction. |
🡪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 property for requests that have been pre-authorised. |
🡪O 🡨O |
||
geoCode |
string |
Indicates the geographic location from where the transaction was initiated. |
🡪O 🡨O |
||
debitParty |
array |
A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. |
🡪C 🡨C |
/transactions API: Mandatory /transactions/type API: debitParty must be supplied if creditParty is omitted. If creditParty is supplied, then debitParty is optional. |
|
creditParty |
array |
A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. |
🡪C 🡨C |
/transactions API: Mandatory /transactions/type API: creditParty must be supplied if debitParty is omitted. If debitParty is supplied, then creditParty is optional. |
|
senderKyc |
object |
A collection of properties detailing the KYC of the transaction Sender, typically used for International Transfers. |
🡪O 🡨O |
||
recipientKyc |
object |
A collection of properties detailed the KYC of the transaction Recipient, typically used for International Transfers. |
🡪O 🡨O |
||
internationalTransfer |
object |
A collection of properties detailing information specifically used for international transfers. |
🡪O 🡨O |
||
originalTransaction |
string |
For reversals and refunds, this property indicates the transaction which is the subject of the reversal. |
🡪O 🡨O |
||
servicingIdentity |
string |
The property is used to identify the servicing identity for transactions, e.g. till, POS ID, assistant ID. |
🡪O 🡨O |
||
requestingLei |
string |
Legal Entity Identifier of the organisation that is requesting the transaction. |
🡪O 🡨O |
Refer to LEI format as defined here: |
|
receivingLei |
string |
Legal Entity Identifier of the organisation that is receiving the transaction. |
🡪O 🡨O |
Refer to LEI format as defined here: |
|
fees |
array |
Allows the passing and/or returning of all fees pertaining to the transaction. |
🡪O 🡨O |
||
metadata |
array |
A collection of key/value pairs. These can be used to populate additional transaction properties. |
🡪O 🡨O |
Reversals API
The Reversals API is used to reverse or adjust/refund a financial transaction. The originating transaction reference must be provided in the path in order to identify the transaction 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.
The supported method and path is POST /transactions/{originalTransactionReference}/reversals.
The object definition for Reversals is provided below.
Reversal Base Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
amount |
string |
The transaction Amount. |
🡪O 🡨O |
Please refer to Amount Validation |
|
currency |
string |
Currency of the transaction amount. |
🡪O 🡨O |
Enumeration = ISO Currency Codes. |
|
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 |
||
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 |
||
requestDate |
date-time |
The creation date and time of the transaction as supplied by the client. |
🡪O 🡨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 |
||
transactionReference |
string |
Unique reference for the transaction. This is returned in the response by API provider. |
🡪NA 🡨M |
||
transactionReceipt |
string |
Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. |
🡪NA 🡨O |
||
geoCode |
string |
Indicates the geographic location from where the transaction was initiated. |
🡪O 🡨O |
||
requesting OrganisationTransactionReference |
string |
A reference provided by the requesting organisation that is to be associated with the transaction. |
🡪O 🡨O |
||
debitParty |
array |
A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. |
🡪O 🡨O |
||
creditParty |
array |
A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. |
🡪O 🡨O |
||
originalTransactionReference |
string |
For reversals and refunds, this property indicates the transaction which is the subject of the reversal. |
🡪NA 🡨M |
||
requesting Lei |
string |
Legal Entity Identifier of the organisation that is requesting the transaction. |
🡪O 🡨O |
Refer to LEI format as defined here: |
|
receiving Lei |
string |
Legal Entity Identifier of the organisation that is receiving the transaction. |
🡪O 🡨O |
Refer to LEI format as defined here: |
|
servicingIdentity |
string |
The property is used to identify the servicing identity for transactions, e.g. till, POS ID, assistant ID. |
🡪O 🡨O |
||
fees |
array |
Allows the passing and/or returning of all fees pertaining to the transaction. |
🡪O 🡨O |
||
metadata |
array |
A collection of key/value pairs. These can be used to populate additional transaction properties. |
🡪O 🡨O |
Introduction to Processing Batch Transactions
The Mobile Money API allows clients to submit, approve and view batches of transactions. The following steps describe an end to end flow for processing batch transactions. Two types of processing modes are supported:
-
One shot processing without an approver.
-
Maker/checker approval, i.e. transactions are not completed until approved via a separate API request.
The individual APIs that are referenced in the steps below are fully documented in subsequent sub-sections.
One-Shot Batch Processing
Creating a Batch
-
Client submits the batch for processing via a ‘POST /batchtransactions’.
-
The client will return the RequestState object indicating whether a callback will be provided or polling is required.
-
The API provider will parse the batch in order to determine whether the transactions are capable of being processed.
Once parsing has completed, the API provider will set the batch status in the batchtransactions object to ‘completed’.
Verifying a Batch
-
The client will be able to retrieve the batchtransactions object by invoking GET /batchtransactions using the object reference provided by the RequestState object. Alternatively, if Callback is specified, the client will receive the representation of the batchtransactions object to their nominated URL set in the X-Callback-URL header.
-
If errors are indicated, i.e. some of the transactions failed parsing, the client is able to retrieve the errors via ‘GET /batchtransactions/rejections’. Successfully completed transactions can be viewed via ‘GET /batchtransactions/completions’.
Approving a Batch
-
A client can approve the batch for posting by issuing a ‘PATCH /batchtransactions’ in order to update the status to ‘approved’.
-
As per step 2, a RequestState object will be returned indicating whether a callback will be provided or polling is required.
-
The API provider will then post the transactions in the batch considering any scheduling considerations.
-
Once posting is completed, the API provider will set the batch status in the batchtransactions object to ‘completed’.
-
The client will be able to retrieve the batchtransactions object by invoking GET /batchtransactions using the object reference provided by the RequestState object. Alternatively, if Callback is specified, the client will receive the representation of the batchtransactions object to their nominated URL set in the X-Callback-URL header.
-
the client will also be able to retrieve a list of successful transaction completions ‘/batchtransactions/completions’ and transaction failures ‘/batchtransactions/rejections’.
Batch Transactions API
This API enables clients to submit and approve a batch of transactions. The API allows transactions of multiple types to be include in a single batch. The following methods and paths are permitted:
-
Submit a batch: ‘POST /batchtransactions’
-
Approve a batch: ‘PATCH /bathtransactions/{batchID}’. The Batch Status needs to be set to ‘approved’.
-
View details regarding batch processing: ‘GET /batchtransactions/{batchID}’
Only asynchronous mode is supported for the POST and PATCH methods. For the GET method, only synchronous mode is supported.
A limit of 999,999 transaction records per batch has been implemented in the Swagger definition.
Batch Transaction Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
batchTitle |
string |
Client-provided title for the batch. |
🡨O 🡨O |
||
batchDescription |
string |
Client-provided description of the batch. |
🡪O 🡨O |
||
batchID |
string |
Identifier for the Batch that is assigned by the API provider. This ID is used by the client on subsequent GET or PATCH methods. |
🡪N/A 🡨M |
||
batchStatus |
string |
Indicates the status of the batch. |
🡪O 🡨M |
Enumeration = created, approved, completed |
|
processingFlag |
Boolean |
Indicates whether the batch is currently undergoing processing by the API Provider. |
🡪N/A 🡨O |
||
scheduledStartDate |
date-time |
If the batch has been scheduled, the expected start time is provided here. |
🡪O 🡨O |
||
creationDate |
date-time |
Indicates when the batch was created as recorded by the API provider. |
🡪NA 🡨M |
||
approvalDate |
date-time |
Indicates when the batch was approved as recorded by the API provider. |
🡪NA 🡨M |
||
completionDate |
date-time |
Indicates when the batch was completed as recorded by the API provider. |
🡪NA 🡨M |
||
rejectionCount |
integer |
Indicates the number of records that have been rejected, either during parsing or during final processing. |
🡪NA 🡨O |
||
parsingSuccessCount |
integer |
Indicates the number of records that have been parsed successfully. |
🡪NA 🡨O |
||
completedCount |
integer |
Indicates the number of records that have been successful completed. |
🡪NA 🡨O |
||
Transactions |
array |
Collection of Transactions that are to be processed. Note that the representation of each completed transaction can be retrieved via the ‘/completions API. |
🡪M 🡨N/A |
Batch Rejections API
This API enables clients to retrieve information on all transactions that have either failed parsing or have failed to be completed. Only the GET method is supported. The path is ‘batchtransactions/{batchID}/rejections’.
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 for which records should be returned. |
toDateTime |
string |
date-time |
Indicates the maximum date for which records should be returned. |
Note: 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).
Batch Rejection Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
transactionReference |
string |
Transaction Reference as assigned by the API provider. |
🡪N/A 🡨O |
||
rejectionDate |
date-time |
Date and time of the rejection. |
🡪N/A 🡨M |
||
debitParty |
array |
The debit party identifiers for the transaction as specific in the batch request. |
🡪N/A 🡨M |
||
creditParty |
array |
The credit party identifiers for the transaction as specific in the batch request. |
🡪N/A 🡨M |
||
rejectionReason |
string |
The reason for the transaction request as indicated by the API provider. |
🡪N/A 🡨M |
||
requestingOrganisationTransactionReference |
string |
A reference provider by the requesting organisation that is to be associated with the transactions. |
🡪N/A 🡨O |
Batch Completions API
This API lists all transactions that have successfully completed for a given batch. Only the GET method is supported. The path format is ‘batchtransactions/{batchID}/completions’.
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 for which records should be returned. |
toDateTime |
string |
date-time |
Indicates the maximum date for which records should be returned. |
Note: 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)..
Batch Completion Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
transactionReference |
string |
Transaction Reference as assigned by the API provider. |
🡪N/A 🡨M |
||
completionDate |
date-time |
Date and time indicating when the transaction was completed. |
🡪N/A 🡨M |
||
link |
string |
Provides a URL to the transaction resource. |
🡪N/A 🡨M |
||
debitParty |
array |
The debit party identifiers for the transaction as specific in the batch request. |
🡪N/A 🡨M |
||
creditParty |
array |
The credit party identifiers for the transaction as specific in the batch request. |
🡪N/A 🡨M |
||
requestingOrganisationTransactionReference |
string |
A reference provider by the requesting organisation that is to be associated with the transactions. |
🡪N/A 🡨O |
Introduction to Accounts APIs
The Accounts APIs are used to support a range of operations on a financial account resource and associated resources. Types of accounts include mobile wallets, financial institution accounts and utility accounts (e.g. for electricity).
Identifying a Target Account
Two methods are provided for identifying an account, the single identifier method and the multiple identifiers method.
Single Identifier Method
In the scenario where one identifier suffices to uniquely identify an account, the following path is to be used: /accounts/{identifierType}/{identifier}.
Multiple Identifiers Method
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 list of permitted account identifiers supported by the Mobile Money API can be found in the Account Identifiers section. As there can be multiple identifiers required to identify the target account, the path uses a ‘$’ delimiter to separate each identifier, up to a limit of three account identifiers.
Supported Account Resources
The Accounts API support operations against accounts and related resources as per below:
-
/accounts/status. Returns the current status for an account. See the Account Status API for more information.
-
/accounts/accountname. Returns all name properties held for the primary identity that is associated with the account. See the Account Name API for more information.
-
/accounts/balance. Returns the balances for the account. See the Account Balances API for more information.
-
/accounts/statemententries. Returns all statement entries for a given account. See the Statement Entries API for more information.
-
/accounts/bills. Returns all outstanding bills for a given account and enables bills to be paid. See the Bills API and Bill Payments API for more information.
-
/accounts/billcompanies. Returns all applicable bill companies for given account. See the Bill Companies API for more information.
-
/accounts/debitmandates. Allows the creation, updating and viewing of debit mandates for a given account. See Debit Mandates API for more information.
-
/accounts/links. Allows the creation, updating and viewing of account to account links for a given account. See Links API for more information.
-
/accounts/authorisationcodes. Allows the creation, updating and viewing of authorisation codes for a given account. See Authorisation Codes API for more information.
Account Transactions API
It is possible to return a range of transactions for an account as per the following methods and paths:
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 for which records should be returned. |
toDateTime |
string |
date-time |
Indicates the maximum date 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)..
Accounts Status API
The Accounts Status API returns a harmonised status of the account. The status enables the client to determine whether transactions can be subsequently posted against the account. Permitted methods and paths are ‘GET /accounts/{identifierType}/{identifier}/status’ or ‘GET /accounts/{Account Identifiers}/status’.
Account Status Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
accountStatus |
string |
Indicates a simplified representation of the account status. This will be shown as ‘available’ or ‘available’. 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 posted with the account identifier(s) will result in an unregistered voucher creation. |
🡪NA 🡨M |
Enumeration = available, unavailable, unregistered |
|
subStatus |
string |
Property can be used to return a provider-specific status for the account. |
🡪NA 🡨O |
||
lei |
string |
Indicates the Legal Entity Identifier of the organisation holding the account. |
🡪NA 🡨O |
Refer to LEI format as defined here: |
Account Balances API
This API defines specific properties for returning balances associated with an account. Permitted methods and 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 account holder. Path for the ‘self’ version is ‘/accounts/balance’.
Balance Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
currentBalance |
string |
The current outstanding balance on the account. |
🡪NA 🡨O |
Please refer to Amount Validation |
|
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 Amount Validation |
|
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 Amount Validation |
|
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 Amount Validation |
|
currency |
string |
Currency for all returned balances. |
🡪NA 🡨O |
Enumeration = ISO Currency Codes |
|
accountStatus |
string |
Indicates a harmonises 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 |
Account Holder Name API
This API defines specific properties for returning account holder name information associated with an account. Permitted methods and paths are ‘GET /accounts/{identifierType}/{identifier}/accountname’ or ‘GET /accounts/{Account Identifiers}/accountname’.
Account Name Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
name |
Reference |
A collection of properties detailing the name of the Primary Account Holder. |
🡪NA 🡨O |
||
lei |
string |
Indicates the Legal Entity Identifier of the organisation holding the account. |
🡪NA 🡨O |
Refer to LEI format as defined here: |
Statement Entries API
The Statement Entries API enables generic representations of transactions to be returned. Typically, the returned representations are used for the purposes of presenting a statement to the account holder. In order to return statement entries, an account or a transaction must be specified. The supported methods and paths are as follows:
To return a specific statement entry:
-
GET /statemententries/{transactionReference}
To return a range of statement entries:
-
GET /accounts/{ identifierType}/{identifier}statemententries or /accounts/{Account Identifiers}/statemententries.
To filter the number of records returned, the following query string parameters 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 for which records should be returned. |
toDateTime |
string |
date-time |
Indicates the maximum date for which records should be returned. |
transactionStatus |
string |
N/A |
Indicates the status of the transactions to be returned. |
displayType |
string |
N/A |
Indicates the Display Type of the transactions to be returned. |
Note 1: For a harmonised behavior, API Providers should make sure that the statement entries 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).
Statement Entries Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
amount |
string |
Amount of the transaction. |
🡪NA 🡨M |
Please refer to Amount Validation |
|
currency |
string |
Currency of the transaction. |
🡪NA 🡨M |
Enumeration = ISO Currency Codes |
|
displayType |
string |
The transaction type that is to be used for presentation to the account holder as determined by the API provider. This is not necessarily the actual transaction type. |
🡪NA 🡨O |
||
transactionStatus |
string |
Indicates the status of the transaction as represented by the API provider. |
🡪NA 🡨M |
||
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. |
🡪NA 🡨O |
||
requestDate |
date-time |
The creation date and time of the transaction as supplied by the client. |
🡪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 modified by the API Provider. |
🡪NA 🡨O |
||
transactionReference |
string |
Unique reference for the transaction. This is returned in the response by API provider. |
🡪NA 🡨M |
||
transactionReceipt |
string |
Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. |
🡪NA 🡨O |
||
debitParty |
array |
A collection of key/value pairs that identify the debit. Keys include MSISDN and Wallet Identifier. |
🡪NA 🡨M |
||
creditParty |
array |
A series of key/value pairs that identify the credit party. Keys include MSISDN and Wallet Identifier. |
🡪NA 🡨M |
Bills API
The Bills API is used to return all outstanding bills associated with an account. The main purpose of the API is to support Bill Presentment, i.e. presenting all applicable bills for a payer to view and select for payment. In order to pay a bill, the Bill Payments API is used. Permitted methods and paths are ‘GET /accounts/{identifierType}/{identifier}/bills’ or ‘GET /accounts/{Account Identifiers}/bills’.
Bill Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
currency |
string |
Currency of the bill to be paid. |
🡪NA 🡨O |
Enumeration = ISO Currency Codes |
|
amountDue |
string |
Amount outstanding on the bill to be paid. |
🡪NA 🡨O |
Please refer to Amount Validation |
|
dueDate |
date |
Date on which the Bill is due to be paid. |
🡪NA 🡨O |
||
billReference |
string |
Reference number for the Bill that the payer can use when making a payment. |
🡪NA 🡨O |
||
minimumAmountDue |
string |
The minimum amount that is outstanding on the bill to be paid. |
🡪NA 🡨O |
Please refer to Amount Validation |
|
billDescription |
string |
Description of the bill that is to be paid. |
🡪NA 🡨O |
||
billStatus |
String |
Identifies the status of the Bill. |
🡪NA 🡨O |
‘paid’, ‘unpaid’, ‘partialpaid’ |
|
metadata |
array |
A collection of key/value pairs. These can be used to return additional information regarding the bill. |
🡪NA 🡨O |
Bills Payments API
The Bills Payments API is used to pay a specific bill associated with an account. Permitted methods and paths are ‘POST /accounts/{identifierType}/{identifier}/bills/{billReference}/payments’ or ‘POST /accounts/{Account Identifiers}/bill/{billReference}/payments’
Both synchronous and asynchronous modes are supported.
Bill Payment Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
currency |
string |
Currency of the amount that is being paid. |
🡪M 🡨M |
Enumeration = ISO Currency Codes |
|
amountPaid |
string |
Amount that is being paid. |
🡪M 🡨M |
Please refer to Amount Validation |
|
billPaymentStatus |
String |
Indicates the status of the bill payment as stored by the API provider. |
🡪N/A 🡨M |
||
serviceProviderPaymentReference |
String |
Reference for the payment generated by the service provider. |
🡪O 🡨O |
||
requestingOrganisation |
String |
The originating mobile money provider or financial institution that holds the wallet/account of the payer. |
🡪O 🡨O |
||
requestingOrganisationTransactionReference |
String |
The mobile money provider’s (or Financial Institution’s) transaction reference used to debit the customer and credit the service provider. |
🡪O 🡨O |
||
customerReference |
string |
Textual reference provided by the customer paying the bill. |
🡪O 🡨O |
||
paymentType |
string |
Describes the type of Bill Payment, i.e. whether a full or partial payment. |
🡪O 🡨O |
Enumeration = ‘fullpayment’, ‘partialpayment’ |
|
supplementaryBillReferenceDetails |
array |
In some cases, a single reference is not sufficient to identify a bill. This key-value collection enables further reference information to be supplied. |
🡪O 🡨O |
||
metadata |
Array |
A collection of key/value pairs. These can be used to populate additional bill payment properties. |
🡪O 🡨O |
||
serviceProviderComment |
String |
Allows the Service Provider to include specific information regarding the bill payment. |
🡪N/A 🡨O |
||
serviceProviderNotification |
String |
Allows the Service Provider to include specific information that will be included on the notification to the customer by the mobile money provider. |
🡪N/A 🡨O |
Bill Companies API
The Bill Companies API is used to return a list of Service Providers that accept Bill Payments. Permitted methods and paths are as per below:
-
Bill Companies irrespective of account:
-
Use ‘GET /billcompanies’ to return a list of all bill payment service providers.
-
Use ‘GET /billcompanies/{serviceProvider}’ to return a specific bill payment service provider.
-
-
Bill Companies for a given account:
-
‘GET /accounts/{identifierType}/{identifier}/billcompanies’ or ‘GET /accounts/{Account Identifiers}/billcompanies’.
-
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 may apply a limit of 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. |
Note: 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).
Bill Companies Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
companyName |
String |
Display Name for the Service Provider. |
🡪NA 🡨M |
||
serviceProvider |
String |
Service Provider Reference Code. |
🡪NA 🡨M |
||
service ProviderType |
String |
Type of Service Provider that accepts payments. |
🡪NA 🡨O |
||
serviceProviderSubType |
String |
Sub-Type of Service Provider. |
🡪NA 🡨O |
||
supplementary ServiceProviderDetails |
Array |
In some cases, further information for a service provider can be returned. This key-value collection enables further information to be supplied. |
🡪NA 🡨O |
Debit Mandates API
The Debit Mandates API is used to enable a mobile money customer to provide prior approval for payments to be taken from their account by the indicated payee. If the amount property is not supplied, the mandate is considered open, i.e. the payee would be able to take any amount. Mandates can be created, changed and inactivated. The permitted methods and paths as follows:
-
Creation: POST /accounts/{identifierType}/{identifier}/debitmandates or POST /accounts/{Account Identifiers}/debitmandates.
-
Update: In order to update a debit mandate, a HTTP PATCH is used. Format is: PATCH /accounts/{identifierType}/{identifier}/debitmandates/{mandateReference} or PATCH /accounts/{Account Identifiers}/debitmandates/{mandateReference}
-
Read. GET /accounts/{identifierType}/{identifier}/debitmandates/{mandateReference} or GET /accounts/{Account Identifiers}/debitmandates/{mandateReference}.
Synchronous and asynchronous modes are supported for the POST and PATCH methods whereas only synchronous mode is supported for the GET method.
Debit Mandate Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
currency |
string |
Currency of the amount limit. |
🡪O 🡨O |
Enumeration = ISO Currency Codes |
|
amountLimit |
string |
The maximum amount that can be taken by the Payee on a payment request. |
🡪O 🡨O |
Please refer to Amount Validation |
|
startDate |
date |
Date on which the mandate starts. If a frequencyType is specified, this will also be the date on which the first payment is to be taken. |
🡪M 🡨M |
||
endDate |
date |
Date on which the Debit Mandate ends. |
🡪O 🡨O |
||
numberOfPayments |
number |
Indicates the number of consecutive payments that are to be taken. |
🡪O 🡨O |
||
frequencyType |
string |
Indicates the frequency for which payments will be taken from the payers account. |
🡪O 🡨O |
Enumeration = Frequency |
|
mandateStatus |
string |
Indicates the status of the Debit Mandate as held in the API Provider system. |
🡪O 🡨O |
Enumeration = active, inactive |
|
mandateReference |
string |
Unique reference provided by the API Provider for the Debit Mandate. |
🡪N/A 🡨M |
||
requestDate |
date-time |
The creation date and time of the Debit Mandate as supplied by the client. |
🡪M 🡨M |
||
creationDate |
date-time |
Date and time when the Debit Mandate was created by the API Provider. |
🡪NA 🡨O |
||
modificationDate |
date-time |
Date and time when the Debit Mandate was modified by the API Provider. |
🡪NA 🡨O |
Links API
The Links API is used to establish a link between two separate accounts on the client and provider systems. 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 methods and paths are as follows:
-
Creation: POST /accounts/{identifierType}/{identifier}/links or POST /accounts/{ Account Identifiers}/links.
-
Update of status and/or mode properties: 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.
Link Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
linkReference |
string |
Indicates the Link reference. This enables a linked account to be uniquely identified. |
🡪NA 🡨M |
||
status |
string |
Indicates the status of the Link. |
🡪M 🡨M |
Enumeration = active, inactive |
|
mode |
string |
Indicates the mode of operation for the Link. |
🡪M 🡨M |
Enumeration = push, pull, both |
|
sourceAccountIdentifiers |
array |
A series of key/value pairs that identify the source account. Keys include MSISDN and Wallet Identifier. |
🡪M 🡨M |
Quotations API
The Quotations API are used to obtain one or multiple quotes for a mobile money customer that wishes to transfer money. The creation of a quote typically involves returning any fees that will be levied on the sending customer and if the request is international, the forex rate. A request is made for a quotation by the requesting Service Provider in response to a customer request. The quotation is calculated and returned. If the customer is satisfied with the quotation, then they can confirm and proceed with a transaction request using the /transactions API.
The following methods paths are permitted:
-
Creation of a quotation: POST /quotations
-
View a quotation: GET /quotations/{Quotation Reference}
Quotation Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
quotationReference |
string |
Unique reference for the Quotation as provided by the API Provider. |
🡪NA 🡨M |
||
quotationStatus |
string |
Indicates the creation state of the Quotation. |
🡪NA 🡨O |
Enumeration = pending, rejected, completed |
|
requestDate |
date-time |
The creation date and time of the Quotation as supplied by the client. |
🡪M 🡨M |
||
creationDate |
date-time |
Date and time when the Quotation was created by the API Provider. |
🡪NA 🡨O |
||
modificationDate |
date-time |
Date and time when the Quotation was modified by the API Provider. |
🡪NA 🡨O |
||
debitParty |
array |
A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. |
🡪M 🡨M |
||
creditParty |
array |
A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. |
🡪M 🡨M |
||
senderKyc |
object |
A collection of properties detailing the KYC of the transaction Sender, typically used for International Transfers. |
🡪O 🡨O |
||
recipientKyc |
object |
A collection of properties detailing the KYC of the transaction Recipient, typically used for International Transfers. |
🡪O 🡨O |
||
requestAmount |
string |
Requested Quotation amount. |
🡪M 🡨M |
Please refer to Amount Validation |
|
requestCurrency |
string |
Currency of the requested Quotation amount. |
🡪M 🡨M |
Enumeration = ISO Currency Codes |
|
type |
string |
The transaction type that the Quotation has been requested for. |
🡪O 🡨O |
Enumeration = Transaction Types |
|
subtype |
string |
The transaction sub-type that the Quotation has been requested for. |
🡪O 🡨O |
||
chosenDeliveryMethod |
string |
The delivery method chosen by the sending end user as the specific delivery method to be used in the quotes received. |
🡪O 🡨O |
Enumeration = Delivery Method |
|
availableDeliveryMethod |
string |
Delivery Method that is possible for the intended recipient. |
🡪NA 🡨O |
Enumeration = Delivery Method |
|
quotes |
array |
A collection of quotes. A quote can be received from a single receiving payment service provider or from multiple providers. |
🡪NA 🡨O |
||
senderBlockingReason |
string |
The reason for blocking the Quotation, based on AML checks on the sender. |
🡪N/A 🡨O |
||
recipientBlockingReason |
string |
The reason for blocking the Quotation, based on AML checks on the recipient. |
🡪N/A 🡨O |
||
metadata |
array |
A collection of key/value pairs. These can be used to populate additional Quotation properties. |
🡪O 🡨O |
Authorisation Codes API
The Authorisation Codes API allows a mobile money payer or payee to generate a code which when presented to the other party, can be redeemed for an amount set by the payer or payee, depending upon the use case. Authorisation Codes are used widely in the industry across a range of use cases, including:
-
ATM Codes for card-less withdrawals. A code is generated in advance by the customer and entered into the ATM to facilitate the withdrawal.
-
Pre-authorisation codes for agent withdrawals. Depending upon the use case, this could involve the agent (payee) generating a code or the customer (payer) generating the code.
-
Pre-authorisation codes for merchant payments. Depending upon the use case, this could involve the merchant (payee) generating a code or the customer (payer) generating the code.
Once an authorisation code has been generated, it can be presented through multiple means, including encoding into a QR code. Typically, an authorisation code will expire.
The following methods and paths are permitted:
-
Generate an Authorisation Code. POST /accounts/{identifierType}/{identifier}/authorisationcodes or POST /accounts/{Account Identifiers}/authorisationcodes
-
Cancel an Authorisation Code. PATCH /accounts/{identifierType}/{identifier}/authorisationcodes/{authorisationCode} or PATCH /accounts/{Account Identifiers}/authorisationcodes/{authorisationCode}.
-
View Authorisations Codes for a given account. GET /accounts/{identifierType}/{identifier}/authorisationcodes/{authorisationCode} or GET /accounts/{Requestor Account Identifiers}/authorisationcodes/{authorisationCode}.
Synchronous and asynchronous modes are supported for the POST and PATCH methods whereas only synchronous mode is supported for the GET method.
Authorisation Codes Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
authorisationCode |
string |
The code that will be presented to the other party for redemption. |
🡪NA 🡨M |
||
codeState |
string |
Indicates the state of the Authorisation Code. |
🡪NA 🡨M |
Enumeration = ‘active’, ‘expired’ |
|
requestDate |
date-time |
The date and time of the request. |
🡪M 🡨O |
||
codeLifetime |
integer |
Indicates the expiry time in seconds of the code. Depending upon the use case, this can be set by the client or server. |
🡪O 🡨O |
Must be positive value. |
|
amount |
string |
Indicates the amount associated with the authorisation code. Typically, this is set by the client. |
🡪O 🡨O |
Please refer to Amount Validation |
|
currency |
string |
Indicates the amount currency. Must be supplied when an amount is supplied. |
🡪O 🡨O |
Enumeration = ISO Currency Codes |
|
amountType |
string |
The amount for the authorisation can be an exact amount or can be a maximum amount, i.e. redemption up to but not higher than the amount specified. |
🡪O 🡨O |
Enumeration = ‘exact’, ‘maximum’ |
|
holdFundsIndicator |
Boolean |
Indicates whether funds should be reserved against the payer’s account where the payer is the requestor. |
🡪O 🡨O |
||
redemptionChannels |
string |
Indicates the channel(s) that the code can be redeemed against, e.g. ATM, Merchant, etc.. |
🡪O 🡨O |
||
redemptionTransactionTypes |
string |
Indicates the Transaction Types(s) that the code can be redeemed against. |
🡪O 🡨O |
||
redemptionAccountIdentifiers |
array |
A series of key/value pairs that identify the account where the code must be redeemed. Only needed if the redemption account needs to be explicitly stated. |
🡪O 🡨O |
||
metadata |
array |
A collection of key/value pairs. These can be used to populate additional properties. |
🡪O 🡨O |
Supporting Objects
International Transfer Information Object
The International Transfer Information object contains details that are specific to international transfers.
International Transfer Information Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
originCountry |
string |
The originating country of the transaction, i.e. the country where the transaction was initiated. |
🡪M 🡨M |
Enumeration = ISO Country Codes |
|
quotationReference |
string |
Reference for the quotation that was provided to the sender. (refer to Quotations API for more information). |
🡪O 🡨O |
||
quoteId |
string |
The specific quote associated with the quotation (refer to Quotes object for more information). |
🡪O 🡨O |
||
receivingCountry |
string |
Destination Country of the international remittance. |
🡪O 🡨O |
||
remittancePurpose |
string |
Property providing a description of the reason for the international remittance. |
🡪O 🡨O |
||
relationshipSender |
string |
Indicates the relationship (if any) between the sender and the receiver. |
🡪O 🡨O |
||
deliveryMethod |
string |
The recipient delivery method as chosen by the sender. |
🡪O 🡨O |
Enumeration = Delivery Method Types |
|
senderBlockingReason |
string |
The reason for blocking the transaction, based on AML checks on the sender. |
🡪NA 🡨O |
||
recipientBlockingReason |
string |
The reason for blocking the transaction, based on AML checks on the recipient. |
🡪NA 🡨O |
KYC Information Object
KYC refers to ‘Know your Customer’. The KYC object contains a number of properties that enable the identity of subject to be verified. KYC is typically provided for international transfers for the sending identity and the receiving identity. There are no mandatory KYC object properties.
KYC Information Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
nationality |
string |
Nationality of the KYC subject. |
🡪O 🡨O |
Enumeration = ISO Country Codes |
|
dateOfBirth |
date |
Birth date of the KYC subject. |
🡪O 🡨O |
||
occupation |
string |
Occupation of the KYC subject. |
🡪O 🡨O |
||
employerName |
string |
Employer name of the KYC subject. |
🡪O 🡨O |
||
contactPhone |
string |
Contact phone number (mobile or landline) of the KYC subject. |
🡪O 🡨O |
Must contain between 6 and 15 consecutive digits First character can contain a ‘+’ or digit Can contain spaces. |
|
gender |
string |
Gender of the KYC Object. |
🡪O 🡨O |
Length=1, Enumeration = (m)ale, (f)emale, (u)nspecified |
|
idDocument |
array |
An array of properties containing the forms of identification that are associated with the subject. |
🡪O 🡨O |
||
postalAddress |
object |
A collection of properties that details the postal address of the KYC subject. |
🡪O 🡨O |
||
subjectName |
object |
Refers to the name properties for the KYC subject. |
🡪O 🡨O |
||
emailAddress |
string |
Email address of the KYC subject. |
🡪O 🡨O |
||
birthCountry |
string |
The country of birth of the KYC subject. |
🡪O 🡨O |
Enumeration = ISO Country Codes |
Name Object
The name object identifies the name details for the subject identity.
Name Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
title |
string |
The given title of the KYC subject, e.g. Mr, Mrs, Dr. |
🡪O 🡨O |
||
firstName |
string |
First name (also referred to as given name) of the KYC subject. |
🡪O 🡨O |
||
middleName |
string |
Middle Name of the KYC subject. |
🡪O 🡨O |
||
lastName |
string |
Surname (also referred to as last or family name) of the KYC subject. |
🡪O 🡨O |
||
fullName |
string |
The full name of the KYC subject. |
🡪O 🡨O |
||
nativeName |
string |
The full name expressed as in the native language. |
🡪O 🡨O |
ID Document Object
As part of KYC information, identification documentation is normally required. The ID Document Object enables documents pertaining to a subject’s identity to be described.
ID Document Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
idType |
string |
Indicates the type of identification for the KYC subject, e.g. passport, driving licence etc.. |
🡪M 🡨M |
Enumeration = ID Types |
|
idNumber |
string |
Reference pertaining to the type of identification for the KYC subject. |
🡪O 🡨O |
||
issueDate |
date |
Date of issue for the identification document. |
🡪O 🡨O |
||
expiryDate |
date |
Date of expiry for the identification document. |
🡪O 🡨O |
||
issuer |
string |
Indicates the organisation/government entity that issued the ID document. |
🡪O 🡨O |
||
issuerPlace |
string |
Place of issue for the identification type. |
🡪O 🡨O |
||
issuerCountry |
string |
Country where the identification type was issued. |
🡪O 🡨O |
Enumeration = ISO Country Codes |
|
otherIdDescription |
string |
Where an ID Type of ‘otherid’ is specified, a description of the type of identification can be provided in this property. |
🡪O 🡨O |
Address Object
he address object holds the postal address of the subject. Due to variability of address information in a number of mobile money markets, only Country is mandatory.
Address Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
addressLine1 |
string |
First line of the address. |
🡪O 🡨O |
||
addressLine2 |
string |
Second line of the address. |
🡪O 🡨O |
||
addressLine3 |
string |
Third line of the address. |
🡪O 🡨O |
||
city |
string |
City/Town. |
🡪O 🡨O |
||
stateProvince |
string |
State or Province. |
🡪O 🡨O |
||
postalCode |
string |
Postal Code. |
🡪O 🡨O |
||
country |
string |
Country. |
🡪M 🡨M |
Enumeration = ISO Country Codes |
Account Identifiers Object
In Mobile Money, there is no single and common method for identifying mobile money accounts and/or transaction parties. Identifiers include MSISDN (Mobile Number), Bank Sort Code, Account Number and Wallet Identifier. The Account Identifier object enables one or multiple identifiers to be provided to enable the recipient system to resolve the account/party.
Account Identifier Object Properties |
|||||
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 |
Quotes Object
The quotes object defines the properties associated with domestic international remittance quotes.
Quotes Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
quoteId |
string |
The unique ID for this quote. |
🡪NA 🡨M |
||
quoteExpiryTime |
date-time |
The timestamp when the quote will expire. |
🡪NA 🡨O |
||
receivingServiceProvider |
string |
The name of the receiving service provider, i.e. the provider that the quote is associated with. |
🡪NA 🡨O |
||
sendingAmount |
string |
Requested quotation amount as supplied by the sender. |
🡪NA 🡨M |
Please refer to Amount Validation |
|
sendingCurrency |
string |
Currency of the requested quotation amount. |
🡪NA 🡨M |
Enumeration = ISO Currency Codes |
|
receivingAmount |
string |
The total amount as it will be received by the receiving end user. |
🡪NA 🡨M |
Please refer to Amount Validation |
|
receivingCurrency |
string |
The currency of the quote. |
🡪NA 🡨M |
Enumeration = ISO Currency Codes |
|
fxRate |
string |
The conversion rate applicable between the sending and the receiving currency for the requested transaction. |
🡪NA 🡨O |
As per Amount Validation with the exception that up-to ten decimal places can be supplied. |
|
deliveryMethod |
string |
The delivery method that is applicable to the quotation. |
🡪NA 🡨O |
Enumeration = Delivery Method Object |
|
fees |
array |
Returns all fees that are applicable to the quote |
🡪NA 🡨O |
Metadata Object
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.
Identifier Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
key |
string |
Identifies the type of additional property. |
🡪M 🡨M |
||
value |
string |
Identifies the value of the additional property. |
🡪M 🡨M |
Supplementary Bill References Object
This object enables additional payment references to be specified for a bill payment 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.
Identifier Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
paymentReferenceType |
string |
Identifies the type of the additional payment reference. |
🡪M 🡨M |
||
paymentReferenceValue |
string |
Identifies the value of the additional payment reference. |
🡪M 🡨M |
Transaction Types Object
This object enables multiple transaction types to be specified along with paired sub-types. This object is used where multiple transaction types need to be passed in an API.
Transaction Type Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
transactionType |
string |
Identifies the Transaction Type. |
🡪M 🡨M |
Enumeration = Transaction Types |
|
transactionSubType |
string |
Identifies the Transaction Sub-Type. |
🡪O 🡨O |
Channel Types Object
This object enables multiple channel types to be specified. This object is used where multiple channel types need to be passed in an API.
Channel Type Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
channelType |
string |
Identifies the Channel Type. |
🡪M 🡨M |
Fees Object
An object that enables fees that are differentiated by type to be provided and/or returned.
Account Identifier Object Properties |
|||||
Name |
Type |
Description |
Reference |
Validation |
|
feeType |
string |
Defines the type of fee. |
🡪M 🡨M |
||
feeCurrency |
string |
Defines the currency for the given fee. |
🡪M 🡨M |
Enumeration = ISO Currency Codes |
|
feeAmount |
string |
Defines the amount of the fee. |
🡪M 🡨M |
Please refer to Amount Validation |
Enumerations
ISO Currency Codes
The three-character alphabetic code for currency as defined by ISO 4217 is to be used for all currency properties. 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.
Transaction Types
A small number of types have been defined to classify the nature of a transaction. Use of these types will enable clients to indicate the type of transaction in a manner that is common regardless of the API provider.
Code |
Description |
billpay |
Payment of bill from a business for goods and/or services. |
deposit |
Exchange of cash in return for e-Money at a physical agent or via ATM |
disbursement |
Disbursement of funds (making payments from an organisation (business, NGO, government entity) to a mobile money recipient. |
transfer |
Transfer of funds between mobile money provider and another provider or financial institution in the same country. |
merchantpay |
Purchases of goods and/or services from shops (payer present) or online (payer not present). |
inttransfer |
Transfer of funds to a recipient in another country, either directly to/from a mobile wallet or via an international money transfer provider. |
adjustment |
General adjustments to an account via an adjustment transaction (e.g. refunds). |
reversal |
Reversal of a prior transaction to return funds to the payer. |
withdrawal |
Exchange of e-Money in return for cash at a physical agent or via ATM |
ID Types
The ID Types enumeration contains accepted identification types. Due to the wide international variation in accepted types of identification, a catch-all type of ‘otherid’ is included.
ID Type |
Description |
passport |
Payment of bill from a business for goods and/or services. |
nationalregistration |
National Registration Number. |
othered |
Catch-all for IDs not on the list. |
drivinglicence |
Driving Licence Number. |
socialsecurity |
Social Security Number. |
alienregistration |
Alien Registration ID. |
nationalidcard |
National Identity Card. |
employer |
Employers Identification. |
taxid |
Tax Identification Number. |
seniorcitizenscard |
Senior Citizens ID Card. |
marriagecertificate |
Marriage Certificate. |
birthcertificate |
Birth Certificate. |
healthcard |
Health Card. |
votersid |
Voters Identification. |
villageelderletter |
Letter of confirmation from village elder. |
pancard |
Credit/debit card number (Primary Account Number). |
officialletter |
Official letter confirming identity. |
Account Identifiers
The Account Identifier enumeration lists all possible means to identify a target account and , the debit and/or credit party. 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 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. |
ISO Country Codes
The two-character alphabetic code for country as defined by ISO 3166 is to be used for all properties specifying a country or nationality. The full list of codes is maintained by the International Organisation for Standardisation. The list can be obtained via the following website - http://www.iso.org/iso/country_codes.
Delivery Method Type
When a customer requests an international transfer quotation they are able to specify their preferred method of delivery of the transfer to the recipient. Permitted delivery methods are provided below.
Delivery Method |
Description |
directtoaccount |
The transfer is to be delivered into the account (wallet) of the recipient. |
agent |
The recipient can visit an agent and get the transferred funds. |
personaldelivery |
a supplementary service where an authorised person can deliver the funds, in hand, to the receiving end user. |
Frequency Type
When requesting a debit mandate, the API client is able to specific the frequency in which the payment should be taken. Valid values are defined in the table below.
Frequency Type |
Description |
weekly |
Payment will be taken weekly. |
fortnight |
Payment will be taken every two weeks. |
monthspecificdate |
Payment to be taken on a specific date every month. |
twomonths |
Payment to be taken every two months. |
threemonths |
Payment to be taken every three months. |
fourmonths |
Payment to be taken every four months. |
sixmonths |
Payment to be taken every six months. |
yearly |
Payment to be taken yearly. |
lastdaymonth |
Payment to be taken on the last calendar day of the month. |
lastdaymonthworking |
Payment to be taken on the last working day of the month according to working days as per the resident country of the account. |
lastmonday |
Payment to be taken on the last Monday of the month. |
lasttuesday |
Payment to be taken on the last Tuesday of the month. |
lastwednesday |
Payment to be taken on the last Wednesday of the month. |
lastthursday |
Payment to be taken on the last Thursday of the month. |
lastfriday |
Payment to be taken on the last Friday of the month. |
lastsaturday |
Payment to be taken on the last Saturday of the month. |
lastsunday |
Payment to be taken on the last Sunday of the month. |
specificdaymonthly |
Payment to be taken on a specific day of the month. |