API Service Definition

< Back
Version 1.1

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.

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

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 

Account Identifiers

/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 

Account Identifiers

/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 

KYC Information

  

recipientKyc

object

A collection of properties detailed the KYC of the transaction Recipient, typically used for International Transfers.

🡪O

🡨O 

KYC Information

  

internationalTransfer
Information

object

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

🡪O

🡨O 

International Transfer Information 

  

originalTransaction
Reference

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: 

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

receivingLei

string

Legal Entity Identifier of the organisation that is receiving the transaction.

🡪O

🡨O

  

Refer to LEI format as defined here: 

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

fees

array

Allows the passing and/or returning of all fees pertaining to the transaction.

🡪O

🡨O

Fees Object

  

metadata

array

A collection of key/value pairs. These can be used to populate additional transaction properties.

🡪O

🡨O 

Metadata

  

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 

Account Identifiers

  

creditParty 

array

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

🡪O

🡨O 

Account Identifiers

  

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: 

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

receiving Lei

string

Legal Entity Identifier of the organisation that is receiving the transaction.

🡪O

🡨O

  

Refer to LEI format as defined here: 

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

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

Fees Object

  

metadata

array

A collection of key/value pairs. These can be used to populate additional transaction properties.

🡪O

🡨O 

Metadata

  

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

  1. Client submits the batch for processing via a ‘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.

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

  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’. Successfully completed transactions can be viewed via ‘GET /batchtransactions/completions’.

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.

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

Transactions

  

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

Account Identifiers

  

creditParty

array

The credit 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

    

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

Account Identifiers

  

creditParty

array

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

🡪N/A

🡨M

Account Identifiers

  

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: 

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

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 

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

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 

Account Identifiers

  

creditParty

array

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

🡪NA

🡨M 

Account Identifiers

  

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

Metadata

  

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

Supplementary Bill References 

  

metadata

Array

A collection of key/value pairs. These can be used to populate additional bill payment properties.

🡪O

🡨O

Metadata

  

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

Supplementary Service Provider Details 

  

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

Account Identifiers 

  

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 

Account Identifier

  

creditParty

array

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

🡪M

🡨M 

Account Identifier

  

senderKyc

object

A collection of properties detailing the KYC of the transaction Sender, typically used for International Transfers.

🡪O

🡨O 

KYC Information

  

recipientKyc

object

A collection of properties detailing the KYC of the transaction Recipient, typically used for International Transfers.

🡪O

🡨O 

KYC Information

  

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 

Quotes

  

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 

Metadata

  

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

Channel Types Object

  

redemptionTransactionTypes

string

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

🡪O

🡨O

Transaction Types Object

  

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 

  

metadata

array

A collection of key/value pairs. These can be used to populate additional properties.

🡪O

🡨O 

Metadata

  

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 

Id Document

  

postalAddress

object

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

🡪O

🡨O 

Address

  

subjectName

object

Refers to the name properties for the KYC subject.

🡪O

🡨O

Name

  

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

Fees Object

  

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.