# API Service Definition

# 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

classDiagram Credit Party Identifier "1..10" --* "1" Transaction Debit Party Identifier "1..10" --* "1" Transaction Fee "0..20" --* "1" Transaction Transaction "1" *-- "0..20" Metadata Transaction "1" *-- "0..2" KYC Information Transaction "1" *-- "0..1" International Transfer Information KYC Information "1" *-- "0..10" ID Document KYC Information "1" *-- "0..1" Address KYC Information "1" *-- "0..1" Name

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 ← C	Account Identifiers	creditParty must be supplied if debitParty is omitted. If debitParty is supplied, then creditParty is optional.
debitParty	array	A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier.	→ C ← C	Account Identifiers	debitParty must be supplied if creditParty is omitted. If creditParty is supplied, then debitParty is optional.
type	string	The harmonised Transaction Type (not required if passed in the URL).	→ M ← M		Enumeration = Transaction Types 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.	→ M ← M		Please refer to API Fundamentals document for amount validation rules.
currency	string	Currency of the transaction amount.	→ M ← M		Enumeration = ISO Currency Codes.
descriptionText	string	Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on a notification SMS and on an account statement.	→ O ← O
fees	array	Allows the passing and/or returning of all fees pertaining to the transaction.	→ O ← O	Fees Object
geoCode	string	Indicates the geographic location from where the transaction was initiated.	→ O ← O
internationalTransferInformation	object	A collection of fields detailing information specifically used for international transfers.	→ O ← 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 ← O
recipientKyc	object	A collection of fields detailing the KYC of the transaction recipient.	→ O ← O	KYC Information
senderKyc	object	A collection of fields detailing the KYC of the transaction sender.	→ O ← 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 ← O
customData	string	A collection of key/value pairs that can be used for provider specific fields.	→ O ← O	Custom Data Object
metadata	array	A collection of key/value pairs. These can be used to populate additional properties that describe administrative information regarding the transaction.	→ O ← O	Metadata

# 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

classDiagram Credit Party Identifier "0..10" --* "" Reversal Debit Party Identifier "0..10" --* "" Reversal Fee "0..20" --* "1" Reversal Metadata "0..20" --* "1" Reversal Reversal --> Transaction

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
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.	→ NA ← M
creditParty	array	A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier.	→ O ← O	Account Identifiers
debitParty	array	A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier.	→ O ← O	Account Identifiers
type	string	The harmonised Transaction Type.	→ M ← M		Enumeration = Transaction Types Note that only Reversals and Refunds (adjustments) are supported.
subType	string	A non-harmonised sub-classification of the type of transaction. Values are not fixed, and usage will vary according to Provider.	→ O ← O
transactionStatus	string	Indicates the status of the transaction as stored by the API provider.	→ NA ← M
amount	string	The transaction amount.	→ O ← O		Please refer to API Fundamentals document for amount validation rules.
currency	string	Currency of the transaction amount.	→ O ← O		Enumeration = ISO Currency Codes.
descriptionText	string	Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on a notification SMS and on an account statement.	→ O ← O
fees	array	Allows the passing and/or returning of all fees pertaining to the transaction.	→ O ← O	Fees Object
geoCode	string	Indicates the geographic location from where the transaction was initiated.	→ O ← O
requestingOrganisation	object	The originating organisation of the request.	→ O ← O	Requesting Organisation
servicingIdentity	string	The field is used to identify the servicing identity for transactions, e.g. till, POS ID, assistant ID.	→ O ← O
transactionReceipt	string	Transaction receipt number as notified to the parties. This may differ from the Transaction Reference.	→ NA ← O
creationDate	date-time	Date and time when the transaction was created by the API Provider.	→ NA ← O
modificationDate	date-time	Date and time when the transaction was modified by the API Provider.	→ NA ← O
requestDate	date-time	The date and time of the transaction request as supplied by the client	→ O ← O
customData	string	A collection of key/value pairs that can be used for provider specific fields.	→ O ← O	Custom Data Object
metadata	array	A collection of key/value pairs. These can be used to populate additional properties that describe administrative information regarding the transaction.	→ O ← O	Metadata

# 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

Client submits the batch for processing via POST /batchtransactions.
The client will return the requestState object indicating whether a callback will be provided or polling is required.
The API provider will parse the batch in order to determine whether the transactions are capable of being processed.
Once parsing has completed, the API provider will set the batch status in the batchTransactions object to ‘completed’.

Verifying a Batch

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

Client submits the batch for processing via POST /batchtransactions.
The client will return the requestState object indicating whether a callback will be provided or polling is required.
The API provider will parse the batch in order to determine whether the transactions are capable of being processed.
Once parsing has completed, the API provider will set the batch status in the batchTransactions object to ‘created’.

Verifying a Batch

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.

Approving a Batch

A client can approve the batch for posting by issuing a PATCH /batchtransactions in order to update the status to ‘approved’.
As per step 2, a requestState object will be returned indicating whether a callback will be provided or polling is required.
The API provider will then post the transactions in the batch considering any scheduling considerations.
Once posting is completed, the API provider will set the batch status in the batchTransactions object to ‘completed’.
The client will be able to retrieve the batchTransactions object by invoking GET /batchtransactions using the object reference provided by the requestState object. Alternatively, if Callback is specified, the client will receive the representation of the batchTransactions object to their nominated URL set in the X-Callback-URL header.

the client will also be able to retrieve a list of successful transaction completions /batchtransactions/completions and transaction failures /batchtransactions/rejections.

# Batch Transactions API

This API enables clients to submit and approve a batch of transactions. The API allows transactions of multiple types to be 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

classDiagram Credit Party Identifier "1..10" --* "1" Transaction Debit Party Identifier "1..10" --* "1" Transaction Fee "0..20" --* "1" Transaction Transaction "0.." --* "1" Batch Transaction Transaction "1" *-- "0..20" Metadata Transaction "1" *-- "0..1" International Transfer Information KYC Information "0..2" --* "1" Transaction KYC Information "1" *-- "0..10" ID Document KYC Information "1" *-- "0..1" Address KYC Information "1" *-- "0..1" Name

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.	→ NA ← 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 ← NA	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.	→ NA ← 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.

TIP

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

classDiagram Credit Party Identifier "1..10" --* "1" Batch Rejection Debit Party Identifier "1..10" --* "1" Batch Rejection Batch Rejection "0..*" --* "1" Batch Transaction

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.	→ NA ← O
requestingOrganisationTransactionReference	string	A reference provided by the requesting organisation that is to be associated with the transactions.	→ NA ← O
creditParty	array	The credit party identifiers for the transaction as specific in the batch request.	→ NA ← M	Account Identifiers
debitParty	array	The debit party identifiers for the transaction as specific in the batch request.	→ NA ← M	Account Identifiers
rejectionReason	string	The reason for the transaction request as indicated by the API provider.	→ NA ← M
rejectionDate	date-time	Date and time of the rejection.	→ NA ← 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.

TIP

# Batch Completion UML Class Diagram

classDiagram Credit Party Identifier "1..10" --* "1" Batch Completion Debit Party Identifier "1..10" --* "1" Batch Completion Batch Completion "0..*" --* "1" Batch Transaction

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.	→ NA ← M
requestingOrganisationTransactionReference	string	A reference provided by the requesting organisation that is to be associated with the transactions.	→ NA ← O
creditParty	array	The credit party identifiers for the transaction as specific in the batch request.	→ NA ← M	Account Identifiers
debitParty	array	The debit party identifiers for the transaction as specific in the batch request.	→ NA ← M	Account Identifiers
completionDate	date-time	Date and time indicating when the transaction was completed.	→ NA ← M
link	string	Provides a URL to the transaction resource.	→ NA ← 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”	UUse 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

classDiagram ID Document "0..10" --* "1" KYC Information Address "0..1" --* "1" KYC Information Name "0..1" --* "1" KYC Information KYC Information "1" --* "1" Identity Account Identifier "1..10" --* "1" Account Identity "1..20" --* "1" Account Fee "1..20" --* "1" Account Commission "1..20" --* "1" Account

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

TIP

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

classDiagram ID Document "0..10" --* "1" KYC Information Address "0..1" --* "1" KYC Information Name "0..1" --* "1" KYC Information Credit Party Identifier "1..10" --* "1" Transaction Debit Party Identifier "1..10" --* "1" Transaction Fee "0..20" --* "1" Transaction KYC Information "0..2" --* "1" Transaction Metadata "0..20" --* "1" Transaction International TransferInformation "0..1" --* "1" Transaction Transaction "0..*" --* "2" Account

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

classDiagram Account Status "1" --* "1" Account

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 (opens new window)

# 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

classDiagram Account Balance "1" --* "1" Account

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

classDiagram Account Holder Name "1" --* "1" Account

Figure 2-10 Account Holder Name UML Class Diagram

# Account Holder Name Object Definition

Account Holder Name Object
Name	Type	Description		Reference	Validation
name	Reference	A collection of fields 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 (opens new window)

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

TIP

Note 1: For a harmonised behavior, API Providers should make sure that the statement entries are returned in descending date created order.

# Account Statement Entry UML Class Diagram

classDiagram Credit Party Identifier "1..10" --* "1" Statement Entry Debit Party Identifier "1..10" --* "1" Statement Entry

classDiagram Credit Party Identifier "1..10" --* "1" Statement Entry Debit Party Identifier "1..10" --* "1" Statement Entry Statement Entry "0..*" --* "2" Account

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 ← M	Account Identifiers
debitParty	array	A collection of key/value pairs that identify the debit. Keys include MSISDN and Wallet Identifier.	→ NA ← M	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 ← O
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.

TIP

Note 1: For a harmonised behavior, API Providers should make sure that the bills are returned in descending date created order.

# Bill UML Class Diagram

classDiagram Metadata "0..20" --* "1" Bill Bill "0..*" --* "1" Account

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.

TIP

Note 1: For a harmonised behavior, API Providers should make sure that the bill payments are returned in descending date created order.

# Bill Payment UML Class Diagram

classDiagram Supplementary Bill Reference "0..20" --* "1" Bill Payment Metadata "0..20" --* "1" Bill Payment

classDiagram Supplementary Bill Reference "0..20" --* "1" Bill Payment Metadata "0..20" --* "1" Bill Payment Bill Payment "0..*" --* "1" Account

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.	→ NA ← 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.	→ NA ← 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.	→ NA ← 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 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.

TIP

# Bill Company UML Class Diagram

classDiagram Supplementary Service Provider Details "0..20" --* "1" Bill Company

classDiagram Supplementary Service Provider Details "0..20" --* "1" Bill Company Bill Company "0..*" --* "1" Account

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
serviceProviderType	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
supplementaryServiceProviderDetails	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

classDiagram Payee Identifiers "0..10" --* "1" Debit Mandate Payer Identifiers "0..10" --* "1" Debit Mandate Debit Mandate "0..*" --* "1" Account

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.	→ NA ← M
payee	array	A series of key/value pairs that enable the payee to be identified. Keys include MSISDN and Wallet Identifier.	→ O ← 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 ← 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

classDiagram Source Account Identifier "1..10" --* "1" Link Link "0..*" --* "1" Account

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.

TIP

Note 1: For a harmonised behavior, API Providers should make sure that the authorisation codes are returned in descending date created order.

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

classDiagram Redemption Account Identifier "0..10" --* "1" Authorisation Code Metadata "0..20" --* "1" Authorisation Code Redemption Channel "0..50" --* "1" Authorisation Code Redemption Transaction Type "0..50" --* "1" Authorisation Code Authorisation Code "0..*" --* "1" Account

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

classDiagram Credit Party Identifier "1..10" --* "1" Quotation Debit Party Identifier "1..10" --* "1" Quotation Metadata "0..20" --* "1" Quotation Quotation "1" *-- "0..2" KYC Information Quotation "1" *-- "0..1" Quote KYC Information "1" *-- "0..10" ID Document KYC Information "1" *-- "0..1" Address KYC Information "1" *-- "0..1" Name Quote "1" *-- "0..20" Fee

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 ← M	Account Identifiers
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 Identifiers
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 ← O	Quotes
recipientKyc	object	A collection of fields detailing the KYC of the transaction recipient, typically used for International Transfers.	→ O ← O	KYC Information
senderKyc	object	A collection of fields detailing the KYC of the transaction sender, typically used for International Transfers.	→ O ← 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.	→ NA ← 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 ← 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 ← 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 ← 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.
emailAddress	string	Email address of the KYC subject.	→ O ← O
employerName	string	Employer name of the KYC subject.	→ O ← O
gender	string	Gender of the KYC Object.	→ O ← 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 ← O	Id Document Object
nationality	string	Nationality of the KYC subject.	→ NA ← O		Enumeration = ISO Country Codes
postalAddress	object	A collection of fields that details the postal address of the KYC subject.	→ O ← O	Address
occupation	string	Occupation of the KYC subject.	→ O ← 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 ← 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
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 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 ← 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 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 ← M		Enumeration = Account Identifiers
value	string	Provides the account identifier type value.	→ M ← 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 ← 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 ← M
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 ← O
receivingServiceProvider	string	The name of the receiving service provider, i.e. the provider that the quote is associated with.	→ NA ← O

# 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 ← 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 ← 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 ← 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 ← 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 ← 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 ← M
feeAmount	string	Defines the amount of the fee.	→ M ← M		Please refer to API Fundamentals document for amount validation rules.
feeCurrency	string	Defines the currency for the given fee.	→ M ← M		Enumeration = ISO Currency Codes

# 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 ← 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 ← 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 ← 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 (opens new window)

# 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 (opens new window) for further information.
sortcode	Bank Sort Code	string	Sort code to identify the financial institution holding the account.
organisationid	Organisation Account Identifier	string	Used to identify the organisation for which a payment is to be made.
username	Username	string	Used to identify target account via an associated username.
walletid	Wallet Identifier	string	A means to identify a mobile money wallet, particularly where multiple wallets can be held against an MSISDN. typically used in conjunction with MSISDN or identity alias to identify a particular wallet.
linkref	Link Reference	string	A means to uniquely identify an account via an account to account link. E.g. wallet account link to bank account.
consumerno	Consumer Number	string	Identifies the consumer associated with the account.
serviceprovider	Service Provider	string	Provides a reference for a Service Provider.
storeid	Store ID	string	Identifies the transacting store / retail outlet.
bankname	Bank Name	string	Name of the bank.
bankaccounttitle	Bank Account Title	string	The title of the bank account.
emailaddress	Email Address	string	emailaddress of the party.
mandatereference	Debit Mandate Reference	string	A means to identify an account via a debit mandate reference.

# 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 (opens new window)

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

← Getting started Open OAS3 UI →