< Back
Version 1.2

API Endpoints

API endpoint fields are described in this specification as follows:

  • The field name.

  • The field type.

  • Description of the field.

  • Optionality of the field, i.e. whether the field must be supplied. Optionality is identified as per 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.

 

  • Reference where the fields is an array and/or is defined by another object.

  • Validation applied to the field, including enumeration, field length and use of regular expressions to validate format. 

Please note that string fields 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. 

The following paths are permitted: 

Operation

Path

Description

POST

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 UML Class Diagram

Figure 2-1 Transaction UML Class Diagram

Transaction Object Definition

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

🡨

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

🡨

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

🡨

   

internationalTransferInformation

object

A collection of fields detailing information specifically used for international transfers.

🡪O

🡨

International Transfer Information 

 

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

🡨

   

recipientKyc

object

A collection of fields detailing the KYC of the transaction recipient.

🡪O

🡨

KYC Information

 

senderKyc 

object

A collection of fields detailing the KYC of the transaction sender.

🡪O

🡨

KYC Information

 

requestingOrganisation

object

The originating organisation of the request.

🡪O

🡨O

Requesting Organisation

 

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

🡨

   

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

🡨

Metadata

 

Reversals API

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 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 and updating reversals, the Transactions API should be used. 

The supported path is POST /transactions/{originalTransactionReference}/reversals.

Reversal UML Class Diagram

Figure 2-2 Reversal UML Class Diagram

Reversal Object Definition

Reversal Object

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

🡨

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

🡨

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

🡨

   

requestingOrganisation

object

The originating organisation of the request.

🡪O

🡨O

Requesting Organisation

 

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

🡨

   

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

🡨

Metadata

 

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 second API request.

The individual APIs that are referenced in the steps below are fully documented in subsequent sub-sections.

Batch Transactions Workflow

One-Shot Batch Processing

Creating a Batch

  1. Client submits the batch for processing via POST /batchtransactions.

  2. The client will return the requestState object indicating whether a callback will be provided or polling is required.

  3. The API provider will parse the batch in order to determine whether the transactions are capable of being processed.

  4. Once parsing has completed, the API provider will set the batch status in the batchTransactions object to ‘completed’. 

 

Verifying a Batch

  1. The client will be able to retrieve the batch transaction 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.

Batch Processing with Maker/Checker

Creating a Batch

  1. Client submits the batch for processing via POST /batchtransactions.

  2. The client will return the requestState object indicating whether a callback will be provided or polling is required.

  3. The API provider will parse the batch in order to determine whether the transactions are capable of being processed.

  4. Once parsing has completed, the API provider will set the batch status in the batchTransactions object to ‘created’.

Verifying a Batch

  1. The client will be able to retrieve the batch transaction 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.

  2. If errors are indicated, i.e. some of the transactions failed parsing, the client is able to retrieve the errors via GET /batchtransactions/rejections.

Approving a Batch

  1. A client can approve the batch for posting by issuing a PATCH /batchtransactions in order to update the status to ‘approved’. 

  2. As per step 2, a requestState object will be returned indicating whether a callback will be provided or polling is required.

  3. The API provider will then post the transactions in the batch considering any scheduling considerations.

  4. Once posting is completed, the API provider will set the batch status in the batchTransactions object to ‘completed’.

  5. 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 included in a single batch. The following 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.

There is a limit of 999,999 transaction records per batch.

Batch Transaction Object UML Diagram

Figure 2-3 Batch Transaction UML Class Diagram

Batch Transaction Object Definition

Batch Transaction Object

Name

Type

Description

 

Reference

Validation

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

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

Transactions

 

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

   

batchTitle

string

Client-provided title for the batch.

🡪O

🡨O

   

batchDescription

string

Client-provided description of the batch.

🡪O

🡨O

   

processingFlag

boolean

Indicates whether the batch is currently undergoing processing by the API Provider.

🡪N/A

🡨O

   

completedCount

integer

Indicates the number of records that have been successfully completed.

🡪NA

🡨O

   

parsingSuccessCount

integer

Indicates the number of records that have been parsed successfully.

🡪NA

🡨O

   

rejectionCount

integer

Indicates the number of records that have been rejected, either during parsing or during final processing.

🡪NA

🡨O

   

requestingOrganisation

object

The originating organisation of the request.

🡪O

🡨O

Requesting Organisation

 

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

🡨O

   

modificationDate

date-time

Indicates when the batch was modified as recorded by the API provider.

🡪NA

🡨O

   

requestDate

date-time

The date and time of the batch 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

 

Batch Rejections API

This API enables clients to retrieve information on all transactions that have either failed parsing or have failed to complete. 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 creationDate for which records should be returned.

toDateTime

string

date-time

Indicates the maximum creationDate 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 UML Class Diagram

Figure 2-4 Batch Rejection UML Class Diagram

Batch Rejection Object Definition

Batch Rejection Object

Name

Type

Description

 

Reference

Validation

transactionReference

string

Transaction Reference as assigned by the API provider.

🡪N/A

🡨O

   

requestingOrganisationTransactionReference

string

A reference provided by the requesting organisation that is to be associated with the transactions.

🡪N/A

🡨O

   

creditParty

array

The credit party identifiers for the transaction as specific in the batch request.

🡪N/A

🡨M

Account Identifiers

 

debitParty

array

The debit party identifiers for the transaction as specific in the batch request.

🡪N/A

🡨M

Account Identifiers

 

rejectionReason

string

The reason for the transaction request as indicated by the API provider.

🡪N/A

🡨M

   

rejectionDate

date-time

Date and time of the rejection.

🡪N/A

🡨M

   

customData 

string

A collection of key/value pairs that can be used for provider specific fields.

🡪O

🡨O

Custom Data Object

 

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 creationDate for which records should be returned.

 

toDateTime

string

date-time

Indicates the maximum creationDate 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 UML Class Diagram

Figure 2-5 Batch Completion UML Class Diagram

Batch Completion Object Definition

Batch Completion Object

Name

Type

Description

 

Reference

Validation

transactionReference

string

Transaction Reference as assigned by the API provider.

🡪N/A

🡨M

   

requestingOrganisationTransactionReference

string

A reference provided by the requesting organisation that is to be associated with the transactions.

🡪N/A

🡨O

   

creditParty

array

The credit party identifiers for the transaction as specified in the batch request.

🡪N/A

🡨M

Account Identifiers

 

debitParty

array

The debit party identifiers for the transaction as specified in the batch request.

🡪N/A

🡨M

Account Identifiers

 

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

   

customData 

string

A collection of key/value pairs that can be used for provider specific fields.

🡪O

🡨O

Custom Data Object

 

Accounts APIs

The Accounts APIs are used to support a range of account-related operations. Types of accounts include mobile wallets, bank accounts, savings accounts, and loan accounts.

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 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.

Account Creation

The Mobile Money API allows account creation for customers who are classified as individuals. The creation of a customer account can be triggered by various means including:

  • Account creation via a mobile money agent.

  • Automatic account creation upon SIM registration.

  • App-based self-registration.

Regardless of the method of creation, new customers are generally provided with account and transaction limits based upon the level of KYC information they have provided and whether their KYC information has been physically verified.

To create an account, use POST /accounts/{identityType}, supplying ‘individual’ as the identityType.

Account Retrieval

Account details, including associated account identities can be retrieved via the following paths:

GET /accounts/{accountIdentifierType}/{identifier} OR

GET /accounts/{Account Identifiers}

Account Update

Account-Level Updates

To update information held against an account, use one of the following paths:

PATCH /accounts/{accountIdentifierType}/{identifier} OR

PATCH /accounts/{Account Identifiers}

 

The following account fields can be updated:

 

Field

PATCH Body

Description

accountStatus

"op": "replace", "path": "/accountStatus", "value": “string”

Use to modify the status of an account.

accountSubStatus

"op": "replace", "path": "/accountSubStatus", "value": “string”

Use to modify the sub-status of an account.


For more information on the above fields please refer to the Account object.

Identity-Level Updates

To update an information held against an identity associated with an account, use one of the following paths:

PATCH /accounts/{identifierType}/{identifier}/identities/{identityId} OR

PATCH /accounts/{Account Identifiers}/identities/{identityId}

 

The following identity fields can be updated:

 

Field

PATCH Body

Description

identity.identityStatus

"op": "replace", "path": "/identityStatus", "value": “string”

Use to modify the status of an identity associated with an account.

identity.kycVerificationStatus

"op": "replace", "path": "/kycVerificationStatus", "value": “string”

Use to change the KYC verification status of an identity associated with an account.

identity.kycVerificationEntity

"op": "replace", "path": "/kycVerificationEntity", "value": “string”

Use to indicate the entity (e.g. mobile money agent) that performed the verification.

identity.kycLevel

"op": "replace", "path": "/kycLevel", "value": “integer”

Use to modify the KYC level of an identity associated with an account.

 

For more information on the above fields please refer to the Identity Object.

Account UML Diagram

Picture 3

Figure 2-6 Account Creation UML Class Diagram

Account Object Definition

Account Object

Name

Type

Description

 

Reference

Validation

accountIdentifiers

array

A series of key/value pairs that enable the account to be identified. Identifiers are assigned by the API Provider during creation.

🡪O

🡨

Account Identifiers

 

identity

array

An account must be associated with one or more identities. 

🡪M

🡨M

Identity Object

 

accountType 

string

A non-harmonised field that indicates the type of the account.

🡪O

🡨O

   

accountStatus

string

Indicates a simplified representation of the account status. 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. 

🡪NA

🡨M

   

accountSubStatus

string

Field can be used to return a provider-specific status for the account.

🡪NA

🡨O

   

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 of the account.

🡪NA

🡨O

 

Enumeration = ISO Currency Codes

customData 

string

A collection of key/value pairs that can be used for provider specific fields.

🡪O

🡨O

Custom Data Object

 

fees

string

Returns all fees related to the creation of the account.

🡪O

🡨O

Fees Object

 

commissionEarned

string

Returns all commission earned by the registering entity for the creation of the account.

🡪NA

🡨O

Commission Object

 

registeringEntity

string

The entity that registered the account, for example, a mobile money agent.

🡪O

🡨O

   

creationDate

date-time

Indicates when the account was created as recorded by the API provider.

🡪NA

🡨O

   

modificationDate

date-time

Indicates when the account was modified as recorded by the API provider.

🡪NA

🡨O

   

requestDate

date-time

The date and time of the account request as supplied by the client.

🡪O

🡨O

   

Retrieving Transactions for an Account

It is possible to return a range of transactions for an account as per the following 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 creationDate for which records should be returned.

toDateTime

string

date-time

Indicates the maximum 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).

Account Transaction UML Class Diagram

Picture 6

Figure 2-7 Account Transaction UML Class Diagram

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 paths are GET /accounts/{identifierType}/{identifier}/status’ or GET /accounts/{Account Identifiers}/status.

Account Status UML Class Diagram

Picture 15

Figure 2-8 Account Status UML Class Diagram

Account Status Object Definition

Account Status Object

Name

Type

Description

 

Reference

Validation

accountStatus

string

Indicates a simplified representation of the account status. 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 posted with the account identifier(s) will result in an unregistered voucher creation.

🡪NA

🡨M

 

Enumeration = available, unavailable, unregistered

subStatus

string

Field 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: 

https://www.leiroc.org/lei.htm

Account Balances API

This API defines specific fields for returning balances associated with an account. 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 account holder. Path for the ‘self’ version is /accounts/balance.

Account Balance UML Class Diagram

 

Picture 16

Figure 2-9 Account Balance UML Class Diagram

 

Balance Object

Name

Type

Description

 

Reference

Validation

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

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

Account Holder Name API

This API defines specific fields for returning account holder name information associated with an account. Permitted paths are GET /accounts/{identifierType}/{identifier}/accountname or GET /accounts/{Account Identifiers}/accountname.

Account Holder Name UML Class Diagram

Figure 2-10 Account Holder Name UML Class Diagram

Account Holder Name Object Definition

Account Holder Name Object

Name

Type

Description

 

Reference

Validation

name

rReference

A collection of fields detailing the name of the Primary Account Holder. 

🡪NA

🡨

Name

 

lei

string

Indicates the Legal Entity Identifier of the organisation holding the account.

🡪NA

🡨O

 

Refer to LEI format as defined here: 

https://www.leiroc.org/lei.htm

Account Statement Entries API

The Account Statement Entries API enables a generic representation of transactions to be returned so that they can be displayed in an account statement for the account holder. To return statement entries, an account or a transaction reference must be specified. The supported 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 creationDate for which records should be returned.

toDateTime

string

date-time

Indicates the maximum creationDate 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).

Account Statement Entry UML Class Diagram

Picture 7

Figure 2-11 Statement Entry UML Class Diagram

Account Statement Entry Object Definition

Account Statement Entry Object

Name

Type

Description

 

Reference

Validation

transactionReference

string

Unique reference for the transaction. This is returned in the response by API provider. 

🡪NA

🡨M

   

creditParty

array

A series of key/value pairs that identify the credit party. Keys include MSISDN and Wallet Identifier.

🡪NA

🡨

Account Identifiers

 

debitParty

array

A collection of key/value pairs that identify the debit. Keys include MSISDN and Wallet Identifier.

🡪NA

🡨

Account Identifiers

 

transactionStatus

string

Indicates the status of the transaction as represented by the API provider.

🡪NA

🡨M

   

amount

string

Amount of the transaction.

🡪NA

🡨M

 

Please refer to API Fundamentals document for amount validation rules.

currency

string

Currency of the transaction.

🡪NA

🡨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.

🡪NA

🡨O

   

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

   

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 modified by the API Provider.

🡪NA

🡨O

   

requestDate

date-time

The date and time of the transaction request as supplied by the client.

🡪NA

🡨

   

customData 

string

A collection of key/value pairs that can be used for provider specific fields.

🡪O

🡨O

Custom Data Object

 

Bills API

The Bills API are 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. To pay a bill, the Bill Payments API is used. Permitted paths are  GET /accounts/{identifierType}/{identifier}/bills or GET /accounts/{Account Identifiers}/bills.

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 creationDate for which records should be returned.

toDateTime

string

date-time

Indicates the maximum creationDate for which records should be returned.


 

Note 1:    For a harmonised behavior, API Providers should make sure that the bills 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).

Bill UML Class Diagram

Picture 20

Figure 2-12 Bill UML Class Diagram

Bill Object Definition

Bill Object

Name

Type

Description

 

Reference

Validation

billReference

string

Reference number for the Bill that the payer can use when making a payment.

🡪NA

🡨O

   

billStatus

string

Identifies the status of the Bill.

🡪NA

🡨O

 

‘paid’, ‘unpaid’, ‘partialpaid’

amountDue

string

Amount outstanding on the bill to be paid.

🡪NA

🡨O

 

Please refer to API Fundamentals document for amount validation rules.

billDescription

string

Description of the bill that is to be paid.

🡪NA

🡨O

   

currency

string

Currency of the bill to be paid.

🡪NA

🡨O

 

Enumeration = ISO Currency Codes

dueDate

date

Date on which the Bill is due to be paid.

🡪NA

🡨O

   

minimumAmountDue

string

The minimum amount that is outstanding on the bill to be paid.

🡪NA

🡨O

 

Please refer to API Fundamentals document for amount validation rules.

creationDate

date-time

Indicates when the bill was created by the API provider.

🡪NA

🡨O

   

modificationDate

date-time

Indicates when the bill was modified by the API provider.

🡪NA

🡨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 bill.

🡪NA

🡨O

Metadata

 

Bill Payments API

The Bill Payments APIs are used to pay a specific bill associated with an account held with a service provider. Bill payments can also be retrieved. Permitted paths are:

Path

Usage

/accounts/{identifierType}/{identifier}/bills/{billReference}/payments

Use when a single identifier suffices to identify the bill account.

/accounts/{Account Identifiers}/bills/{billReference}/payments

Use when two or three identifiers are required to identify an account.

/bills/{billReference}/payments

Use when a bill payment is not associated with a service provider account.

/accounts/{identifierType}/{identifier}/bills/payments OR /accounts/{Account Identifiers}/bills/payments

Use when a bill does not have a bill reference

As per MM API standards, POST is used to create a bill payment whereas GET is used to retrieve all payments associated with a bill.

When retrieving bill payments, the following query string parameters can be used to filter the number of records returned:

 

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 creationDate for which records should be returned.

toDateTime

string

date-time

Indicates the maximum creationDate for which records should be returned.

 

Note 1:    For a harmonised behavior, API Providers should make sure that the bill payments 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).

Bill Payment UML Class Diagram

Picture 21

Figure 2-13 Bill Payment UML Class Diagram

Bill Payment Object Definition

Bill Payment Object

Name

Type

Description

 

Reference

Validation

serviceProviderPaymentReference

string

Reference for the payment generated by the service provider.

🡪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

   

paymentType

string

Describes the type of Bill Payment, i.e. whether a full or partial payment.

🡪O

🡨O

 

Enumeration = ‘fullpayment’, ‘partialpayment’

billPaymentStatus

string

Indicates the status of the bill payment as stored by the API provider.  

🡪N/A

🡨M

   

amountPaid

string

Amount that is being paid.

🡪M

🡨M

 

Please refer to API Fundamentals document for amount validation rules.

currency

string

Currency of the amount that is being paid.

🡪M

🡨M

 

Enumeration = ISO Currency Codes

customerReference

string

Textual reference provided by the customer paying the bill.

🡪O

🡨O

   

requestingOrganisation

string

The originating mobile money provider or financial institution that holds the wallet/account of the payer.

🡪O

🡨O

   

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.

🡪C

🡨C

Bill References 

Not applicable if billReference is no passed in the path.

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

   

creationDate

date-time

Indicates when the bill payment was created as recorded by the API provider.

🡪NA

🡨O

   

modificationDate

date-time

Indicates when the bill payment was modified as recorded by the API provider.

🡪NA

🡨O

   

requestDate

date-time

The date and time of the bill payment 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 bill payment.

🡪O

🡨O

Metadata

 

Bill Companies API

The Bill Companies APIs are used to return a list of Service Providers that accept bill payments. Permitted 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 Company UML Class Diagram

Picture 22

Figure 2-14 Bill Company UML Class Diagram

Bill Company Object Definition

Bill Companies Object

Name

Type

Description

 

Reference

Validation

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

   

companyName

string

Display Name for the Service Provider.

🡪NA

🡨M

   

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

Supplementary Service Provider Details 

 

Debit Mandates API

The Debit Mandates APIs allow a mobile money customer to provide prior approval for payments to be taken from their account by a requesting payee. If the amount limit field is not supplied, the payee will be able to take any amount. Mandates can be open-ended or can be constrained by a quantified number of payments for a given frequency.

Mandates can be created, viewed, and modified. The request to create a debit mandate will be typically initiated by the service provider (payee) but can also be requested by the customer (payer).

The permitted paths are as follows. Note that the payer account is identified in the path whereas the payee account is identified in the request body. 

  • 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.

The following fields are modifiable: mandateStatus, startDate, endDate, frequencyType, numberOfPayments.

Debit Mandate UML Class Diagram

Picture 2

Figure 2-15 Debit Mandate UML Class Diagram

Debit Mandate Object Definition

Debit Mandate Object

Name

Type

Description

 

Reference

Validation

mandateReference

string

Unique reference provided by the API Provider for the Debit Mandate.

🡪N/A

🡨M

   

payee

array

A series of key/value pairs that enable the payee to be identified. Keys include MSISDN and Wallet Identifier.

🡪O

🡨

Account Identifiers

 

mandateStatus

string

Indicates the status of the Debit Mandate as held in the API Provider system.

🡪O

🡨O

 

Enumeration = active, inactive

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

   

amountLimit

string

The maximum amount that can be taken by the Payee on a payment request.

🡪O

🡨O

 

Please refer to API Fundamentals document for amount validation rules.

currency

string

Currency of the amount limit.

🡪O

🡨O

 

Enumeration = ISO Currency Codes

endDate

date

Date on which the Debit Mandate ends.

🡪O

🡨O

   

frequencyType

string

Indicates the frequency for which payments will be taken from the payers account.

🡪O

🡨O

 

Enumeration = Frequency

numberOfPayments

number

Indicates the number of consecutive payments that are to be taken.

🡪O

🡨O

   

requestingOrganisation

object

The originating organisation of the request.

🡪O

🡨O

Requesting Organisation

 

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

   

requestDate

date-time

The date and time of the debit mandate request as supplied by the client.

🡪O

🡨

   

customData 

string

A collection of key/value pairs that can be used for provider specific fields.

🡪O

🡨O

Custom Data Object

 

Links API

The Links APIs are 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 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.

Link UML Class Diagram

Picture 8

Figure 2-16 Link UML Class Diagram

Link Object Definition

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

 

Authorisation Codes API

The Authorisation Codes APIs allow a payer to generate a payment code which when presented to the payee, can be redeemed for an amount associated with the code. 

Authorisation codes can be set to expire. Note that expiry time can be specified via the API, however the mobile money provider may mandate a common expiry period for all codes.

 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-authorised codes for agent withdrawals. A code is generated in advance by the customer and given to the agent to facilitate the withdrawal. 

  • Pre-authorised codes for merchant payments. The customer generates a code which can be redeemed at a merchant.

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 paths are permitted:

  • Generate an Authorisation Code. POST /accounts/{identifierType}/{identifier}/authorisationcodes or POST /accounts/{Account Identifiers}/authorisationcodes

  • Cancel an Authorisation Code (codeState = ‘cancelled’). PATCH /accounts/{identifierType}/{identifier}/authorisationcodes/{authorisationCode} or PATCH /accounts/{Account Identifiers}/authorisationcodes/{authorisationCode}

  • View An Authorisation Code for a given account. GET /accounts/{identifierType}/{identifier}/authorisationcodes/{authorisationCode} or GET /accounts/{Requestor Account Identifiers}/authorisationcodes/{authorisationCode}

  • View all Authorisation Codes for a given account. GET /accounts/{identifierType}/{identifier}/authorisationcodes or GET /accounts/{Requestor Account Identifiers}/authorisationcodes.

When retrieving authorisation codes, the following query string parameters can be used to filter the number of records returned:

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 creationDate for which records should be returned.

toDateTime

string

date-time

Indicates the maximum creationDate for which records should be returned.

codeState

string

string

Allows filtering on the state of the authorisation code.

 

Note 1:    For a harmonised behavior, API Providers should make sure that the authorisation codes 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).

Synchronous and asynchronous modes are supported for the POST and PATCH methods whereas only synchronous mode is supported for the GET method.

Authorisation Code UML Class Diagram

Figure 2-17 Authorisation Code UML Class Diagram

Authorisation Code Object Definition

Authorisation Codes Object

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’, ‘cancelled’

amount

string

Indicates the amount associated with the authorisation code. Typically, this is set by the client.

🡪O

🡨O

 

Please refer to API Fundamentals document for amount validation rules.

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’

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

 

If supplied, then must be 1 second or greater.

holdFundsIndicator

boolean

Indicates whether funds should be reserved against the payer’s account where the payer is the requestor.

🡪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

Account Identifiers 

 

redemptionChannels

string

Indicates the channel(s) that the code can be redeemed against, e.g. ATM, Merchant, etc..

🡪O

🡨O

Channel Types Object

 

redemptionTransactionTypes

string

Indicates the Transaction Types(s) that the code can be redeemed against. 

🡪O

🡨O

Transaction Types Object

 

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 request as provided 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 authorisation code.

🡪O

🡨

Metadata

 

Quotations API

The Quotations APIs are used to obtain one or multiple quotes for a mobile money customer that wishes to transfer money. The creation of a quote 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 paths are permitted:

  • Creation of a quotation: POST /quotations

View a quotation: GET /quotations/{Quotation Reference}

Quotation UML Class Diagram

Figure 2-18 Quotation UML Class Diagram

Quotation Object Definition

Quotation Object Definition

Name

Type

Description

 

Reference

Validation

quotationReference 

string

Unique reference for the quotation as provided by the API Provider.

🡪NA

🡨M

   

creditParty

array

A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier.

🡪M

🡨

Account Identifier

 

debitParty

array

A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier.

🡪M

🡨

Account

Identifier

 

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

   

quotationStatus 

string

Indicates the creation state of the quotation. 

🡪NA

🡨O

 

Enumeration = pending, rejected, completed

requestAmount

string

Requested Quotation amount.

🡪M

🡨M

 

Please refer to API Fundamentals document for amount validation rules.

requestCurrency

string

Currency of the requested quotation amount.

🡪M

🡨M

 

Enumeration = ISO Currency Codes

availableDeliveryMethod

string

Delivery Method that is possible for the intended recipient.

🡪NA

🡨O

 

Enumeration = Delivery Method

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

originCountry

string

The originating country of the quotation request, i.e. the country where the request was initiated.

🡪O

🡨O

   

receivingCountry

String

Destination country of the quotation request, i.e. the country that the sender wishes to send to.

🡪O

🡨O

   

quotes

array

A collection of quotes. A quote can be received from a single receiving financial service provider or from multiple providers.

🡪NA

🡨

Quotes

 

recipientKyc

object

A collection of fields detailing the KYC of the transaction recipient, typically used for International Transfers.

🡪O

🡨

KYC Information

 

senderKyc

object

A collection of fields detailing the KYC of the transaction sender, typically used for International Transfers.

🡪O

🡨

KYC Information

 

recipientBlockingReason

string

The reason for blocking the quotation, based on AML checks on the recipient.

🡪NA

🡨O

   

senderBlockingReason

string

The reason for blocking the quotation, based on AML checks on the sender.

🡪NA

🡨O

   

requestingOrganisation

object

The originating organisation of the request.

🡪O

🡨O

Requesting Organisation

 

sendingServiceProviderCountry

string

The country of the sending service provider that holds the account of the sender.

🡪O

🡨O

   

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

   

requestDate

date-time

The date and time of the quotation request as supplied by the client.

🡪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 quotation.

🡪O

🡨

Metadata

 

Supporting Objects

International Transfer Information Object

The International Transfer Information object contains details that are specific to international money transfers.

International Transfer Information Object

Name

Type

Description

 

Reference

Validation

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

   

originCountry

String

The originating country of the transaction, i.e. the country where the transaction was initiated.

🡪M

🡨M

 

Enumeration = ISO Country Codes

deliveryMethod

string

The recipient delivery method as chosen by the sender.

🡪O

🡨O

 

Enumeration = Delivery Method Types

receivingCountry

string

Destination country of the international transfer.

🡪O

🡨O

   

relationshipSender

string

Indicates the relationship (if any) between the sender and the receiver.

🡪O

🡨O

   

recipientBlockingReason

string

The reason for blocking the transaction, based on AML checks on the recipient.

🡪NA

🡨O

   

senderBlockingReason

string

The reason for blocking the transaction, based on AML checks on the sender.

🡪NA

🡨O

   

remittancePurpose

string

field providing a description of the reason for the international transfer.

🡪O

🡨O

   

sendingServiceProviderCountry

string

The country of the sending service provider that holds the account of the sender.

🡪O

🡨O

   

KYC Information Object

KYC refers to ‘Know your Customer’. The KYC object contains a number of fields that enable the identity of the subject to be verified. KYC can be provided with transfers for the sending identity and the receiving identity. There are no mandatory KYC object fields.

KYC Information Object

Name

Type

Description

 

Reference

Validation

birthCountry

string

The country of birth of the KYC subject.

🡪O

🡨O

 

Enumeration = ISO Country Codes

dateOfBirth

date

Birth date of the KYC subject.

🡪O

🡨

   

contactPhone

string

Contact phone number (mobile or landline) of the KYC subject. 

🡪O

🡨

 

Must contain between 6 and 15 consecutive digits

First character can contain a ‘+’ or digit

Can contain spaces.

emailAddress

string

Email address of the KYC subject.

🡪O

🡨O

   

employerName

string

Employer name of the KYC subject.

🡪O

🡨

   

gender

string

Gender of the KYC Object.

🡪O

🡨

 

Length=1, Enumeration = (m)ale, (f)emale, (u)nspecified

idDocument

array

An array of fields containing the forms of identification that are associated with the subject.

🡪O

🡨

Id Document

 

nationality

string

Nationality of the KYC subject.

🡪O

🡨

 

Enumeration = ISO Country Codes

postalAddress

object

A collection of fields that details the postal address of the KYC subject.

🡪O

🡨

Address

 

occupation

string

Occupation of the KYC subject.

🡪O

🡨

   

subjectName

object

Refers to the name fields for the KYC subject.

🡪O

🡨O

Name

 

Name Object

The name object identifies the name details for the subject identity.

Name Object

Name

Type

Description

 

Reference

Validation

title

string

The given title of the KYC subject, e.g. Mr, Mrs, Dr.

🡪O

🡨

   

firstName

string

First name (also referred to as given name) of the KYC subject.

🡪O

🡨

   

middleName

string

Middle Name of the KYC subject.

🡪O

🡨

   

lastName

string

Surname (also referred to as last or family name) of the KYC subject.

🡪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

Name

Type

Description

 

Reference

Validation

idType

string

Indicates the type of identification for the KYC subject, e.g. passport, driving licence etc..

🡪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

🡨

   

expiryDate

date

Date of expiry for the identification document.

🡪O

🡨

   

issuer

string

Indicates the organisation/government entity that issued the ID document.

🡪O

🡨

   

issuerPlace

string

Place of issue for the identification type.

🡪O

🡨

   

issuerCountry 

string

Country where the identification type was issued. 

🡪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 field.

🡪O

🡨O

   

Address Object

The address object holds the postal address of the subject. Due to variability of address information in a number of mobile money markets, only the country is mandatory.

Address Object

Name

Type

Description

 

Reference

Validation

addressLine1

string

First line of the address.

🡪O

🡨

   

addressLine2

string

Second line of the address.

🡪O

🡨O

   

addressLine3

string

Third line of the address.

🡪O

🡨

   

city

string

City/Town.

🡪O

🡨

   

stateProvince

string

State or Province.

🡪O

🡨

   

postalCode

string

Postal Code.

🡪O

🡨

   

country

string

Country.

🡪M

🡨

 

Enumeration = ISO Country Codes

Account Identifier Object

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

Name

Type

Description

 

Reference

Validation

key

string

Provides the account identifier type.

🡪M

🡨

 

Enumeration = Account Identifiers

value

string

Provides the account identifier type value.

🡪M

🡨

   

Identity Object

The Identity object defines the information for an identity associated with an account. Between one and twenty identities can be associated with an account.

Identity Object

Name

Type

Description

 

Reference

Validation

identityId

string

A unique id for the identity as assigned by the API Provider.

🡪NA

🡨M

   

identityType

string

Indicates the type of the identity. Currently, only ‘individual’ is supported.

🡪NA

🡨M

 

‘individual’

identityStatus

string

A non-harmonised field describing the status of the identity.

🡪NA

🡨O

   

identityKyc

object

A collection of fields detailing the KYC held for the identity.

🡪M

🡨

KYC Information

 

accountRelationship

string

Describes the relationship that the identity holds with the account.

🡪M

🡨M

 

‘accountholder’

kycVerificationStatus

string

Indicates the status of the identity’s KYC verification. 

🡪O

🡨O

 

‘verified’, ‘unverified’, ‘rejected’

kycVerificationEntity

string

Indicates the entity (e.g. mobile money agent) that has verified the KYC of the identity.

🡪O

🡨O

   

kycLevel

integer

Indicates the KYC level that the identity is associated with.

🡪O

🡨O

   

customData

array

A collection of key/value pairs that can be used for provider specific fields.

🡪O

🡨O

   

Quote Object

Quotations can consist of multiple quotes. The fields for a quote are defined in the object. 

Quote Object

Name

Type

Description

 

Reference

Validation

quoteId

string

The unique ID for this quote.

🡪NA

🡨

   

receivingAmount

string

The total amount as it will be received by the receiving end user.

🡪NA

🡨M

 

Please refer to API Fundamentals document for amount validation rules.

receivingCurrency

string

The currency of the quote.

🡪NA

🡨M

 

Enumeration = ISO Currency Codes

sendingAmount

string

Requested quotation amount as supplied by the sender.

🡪NA

🡨M

 

Please refer to API Fundamentals document for amount validation rules.

sendingCurrency

string

Currency of the requested quotation amount.

🡪NA

🡨M

 

Enumeration = ISO Currency Codes

deliveryMethod

string

The delivery method that is applicable to the quotation.

🡪NA

🡨O

 

Enumeration = Delivery Method 

fees

array

Returns all fees that are applicable to the quote.

🡪NA

🡨O

Fees Object

 

fxRate

string

The conversion rate applicable between the sending and the receiving currency for the requested transaction.

🡪NA

🡨O

 

Please refer to API Fundamentals document for amount validation rules. Note 10 decimal places supported.

quoteExpiryTime

date-time

The timestamp when the quote will expire.

🡪NA

🡨

   

receivingServiceProvider

string

The name of the receiving service provider, i.e. the provider that the quote is associated with.

🡪NA

🡨

   

Metadata Object

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.

Metadata Object

Name

Type

Description

 

Reference

Validation

key

string

Identifies the type of additional fields.

🡪M

🡨

   

value

string

Identifies the value of the additional field.

🡪M

🡨M

   

Custom Data Object

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.

Custom Data Object

Name

Type

Description

 

Reference

Validation

key

string

Identifies the type of additional fields.

🡪M

🡨

   

value

string

Identifies the value of the additional field.

🡪M

🡨M

   

Supplementary Bill Reference Object

This object enables additional payment references to be specified for a bill payment 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.

Supplementary Bill Reference Object

Name

Type

Description

 

Reference

Validation

paymentReferenceType

string

Identifies the type of the additional payment reference.

🡪M

🡨

   

paymentReferenceValue

string

Identifies the value of the additional payment reference.

🡪M

🡨M

   

Transaction Type 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

Name

Type

Description

 

Reference

Validation

transactionType

string

Identifies the Transaction Type.

🡪M

🡨

 

Enumeration = Transaction Types

transactionSubType

string

Identifies the Transaction Sub-Type.

🡪O

🡨O

   

Channel Type 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

Name

Type

Description

 

Reference

Validation

channelType

string

Identifies the Channel Type.

🡪M

🡨

   

Fees Object

An object that enables fees that are differentiated by type to be provided and/or returned.

Fees Object

Name

Type

Description

 

Reference

Validation

feeType

string

Defines the type of fee.

🡪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

🡨

 

Enumeration = ISO Currency Codes

Commission Object

An object that enables earned commission that is calculated by the API provider to be returned.

Commission Object

Name

Type

Description

 

Reference

Validation

commissionType

string

Defines the type of commission.

🡪M

🡨

   

commissionAmount

string

Defines the amount of the commission.

🡪M

🡨M

 

Please refer to API Fundamentals document for amount validation rules.

commissionCurrency

string

Defines the currency of the commission.

🡪M

🡨

 

Enumeration = ISO Currency Codes

Requesting Organisation Object

An object that details the originating organisation of the request.

Requesting Organisation Object

Name

Type

Description

 

Reference

Validation

requestingOrganisationIdentifierType

string

Identifies the identifier type of the requesting organisation.

🡪M

🡨

 

‘swiftbic’, ‘lei’, ‘organisationid’

requestingOrganisationIdentifier

string

Contains the requesting organisation identifier.

🡪M

🡨M

   

Enumerations

ISO Currency Codes

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.

Transaction Types

A transaction type is used to classify the nature of a transaction.

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. 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 fields 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 Types

When a customer requests a 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 specify the frequency of 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.