< Back
Version 1.0

API Service Definition

Transactions APIs

The Transactions API is used for all operations involving mobile money financial transactions. This currently covers:

  • Creating a Transaction (POST)
  • Returning a representation of one or more transactions(GET)

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.

URI is consistent for all transactions and format is:

/transactions.

The specific resource can be identified by Transaction Reference as per below:

Operation Identifier Identifier Placement
GET Transaction Reference The format is /transactions/{Transaction Reference}
 

Transactions API

Click here to view the Swagger API Definition

The object definition for Transactions as provided below:

Name Type Description Request Response Reference Validation
Amount String Principle Transaction Amount Mandatory Mandatory   Regular Expression – please refer to Swagger definition
Currency String Currency of the principal transaction amount. Mandatory Mandatory   Enumeration = ISO Currency Codes
Type String The harmonised Transaction Type Mandatory Mandatory   Enumeration = Transaction Types
Sub-type String A non-harmonised sub-classification of the type of transaction. Values are not fixed and usage will vary according to Provider. Optional Optional    
Transaction Status String Indicates the status of the transaction as stored by the API provider. Optional Mandatory    
Description Text String Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on the SMS and on the account statement. NA Optional    
Request Date DateTime The creation date and time of the transaction as supplied by the client. Mandatory Mandatory    
Date Created DateTime Date and time when the transaction was created by the API Provider NA Optional    
Date Modified DateTime Date and time when the transaction was modified by the API Provider NA Optional    
Transaction Reference String Unique reference for the transaction. This is returned in the response by API provider. NA Mandatory    
Transaction Receipt String Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. NA Optional    
Requesting Organisation Transaction Reference String A reference provided by the requesting organisation that is to be associated with the transaction. Optional Optional    
One Time Code String A one-time code that can be supplied in the request or can be generated in the response depending upon the use case. Optional Optional    
Geo Code String Indicates the geographic location from where the transaction was initiated. Optional Optional    
Debit Party Identifier Reference Array A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. Mandatory Mandatory Account Identifiers  
Credit Party Identifier Reference Array A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. Mandatory Mandatory Account Identifiers  
Sender KYC Reference A collection of properties detailing the KYC of the transaction Sender, typically used for International Transfers. Optional Optional KYC Information  
Recipient KYC Reference A collection of properties detailed the KYC of the transaction Recipient, typically used for International Transfers. Optional Optional KYC Information  
International Transfer Information Reference A collection of properties detailed information specifically used for international transfers. Optional Optional International Transfer Information  
Original Transaction Reference String For reversals and refunds, this property indicates the transaction which is the subject of the reversal Optional Optional    
Servicing Identity String The property is used to identify the servicing identity for ‘present’ transactions, e.g. till, POS ID, assistant ID Optional Optional    
Requesting LEI String Legal Entity Identifier of the organisation that is requesting the transaction. Optional Optional   Length = 20, Regular Expression (See Swagger Definition)
Receiving LEI String Legal Entity Identifier of the organisation that is receiving the transaction. Optional Optional   Length = 20, Regular Expression (See Swagger Definition)
Metadata Reference Array A collection of key/value pairs. These can be used to populate additional transaction properties. Optional Optional Metadata  

Try it Out - Create a Transaction

Try it Out - View a Transaction

Reversals API

The Reversals API is used to reverse a financial transaction. The originating transaction reference must be provided in the URI in order to identify the transaction to be reversed. For a partial reversal, the amount needs to be supplied. It should be noted however that API Providers may not support partial reversals and will return an error if a partial amount is supplied. This API can also be used for adjustments.

Note that only reversal creation is supported. For viewing reversals, the Transactions API should be used. Format is:

/transactions/{Original Transaction Reference}/reversals

The object definition for Reversals is provided below:

Name Type Description Request Response Reference Validation
Amount String Principle Transaction Amount Optional Optional   Regular Expression – please refer to Swagger definition
Currency String Currency of the principal transaction amount. Optional Optional   Enumeration = ISO Country Codes.
Type String The harmonised Transaction Type Mandatory Mandatory   Enumeration = Transaction Types
Note that only Reversals and Adjustments are supported.
Sub-type String A non-harmonised sub-classification of the type of transaction. Values are not fixed and usage will vary according to Provider. Optional Optional    
Transaction Status String Indicates the status of the transaction as stored by the API provider. Optional Mandatory    
Description Text String Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on the SMS and on the account statement. Optional Optional    
Request Date DateTime The creation date and time of the transaction as supplied by the client. Mandatory Mandatory    
Date Created DateTime Date and time when the transaction was created by the API Provider NA Optional    
Date Modified DateTime Date and time when the transaction was modified by the API Provider NA Optional    
Transaction Reference String Unique reference for the transaction. This is returned in the response by API provider. NA Mandatory    
Transaction Receipt String Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. NA Optional    
Requesting Organisation Transaction Reference String A reference provided by the requesting organisation that is to be associated with the transaction. Optional Optional    
Geo Code String Indicates the geographic location from where the transaction was initiated. Optional Optional   Regular Expression – please refer to Swagger definition
Debit Party Identifier Reference Array A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. Optional Optional Account Identifiers  
Credit Party Identifier Reference Array A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. Optional Optional Account Identifiers  
Original Transaction Reference String For reversals and refunds, this property indicates the transaction which is the subject of the reversal NA Mandatory    
Servicing Identity String The property is used to identify the servicing identity for ‘present’ transactions, e.g. till, POS ID, assistant ID Optional Optional    
Metadata Reference Array A collection of key/value pairs. These can be used to populate additional transaction properties. Optional Optional Metadata  

Try it Out - Create a Reversal

Batch Transactions API Overview

As the name implies, this API allows clients to submit batches of transactions in a single HTTP request. Batch processing is always asynchronous. Batch processing follows a simple state transition:

  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.
  4. Once parsing has completed, the API provider will set the batch status in the batchtransactions object to ‘created’.
  5. The client will be able to retrieve the batchtransactions object by invoking the URI provided by the RequestState object.
  6. If errors are indicated, i.e. some of the transactions failed parsing, the client is able to retrieve the errors via ‘GET /batchtransactions/rejections’.
  7. Depending upon the business process, the client (or another client) can approve the batch for posting by issuing a ‘PATCH /batchtransactions’ in order to update the status to ‘approved’.
  8. As per step 2, a RequestState object will be returned indicating whether a callback will be provided or polling is required.
  9. The API provider will then post the transactions in the batch taking into account any scheduling considerations.
  10. Once posting is completed, the API provider will set the batch status in the batchtransactions object to ‘completed’.
  11. The client will be able to retrieve the batchtransactions object by invoking the URI provided by the RequestState object.
  12. The client will also be able to retrieve a list of successful transaction completions ‘/batchtransactions/completions’ and transaction failures ‘/batchtransactions/rejections’.

Batch Transactions API

As described above, 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 operations are supported:

  • Submit a batch:
    POST /batchtransactions
  • Approve a batch: The Batch Status needs to be set to ‘approved’
    PATCH /bathtransactions/{Batch ID}
  • View details regarding batch processing:
    GET /batchtransactions/{batch ID}
Batch Transaction Object Properties
Name Type Description Request Response Reference Validation
Batch Title String Client-provided title for the batch Optional Optional    
Batch Description String Client-provided description of the batch. Optional Optional    
Batch ID String Identifier for the Batch that is assigned by the API provider. This ID is used by the client on subsequent GET or PATCH operations. N/A Mandatory    
Batch Status String Indicates the status of the batch. Optional Mandatory   Enumeration = created, approved, completed
Processing Flag Boolean Indicates whether the batch is currently undergoing processing by the API Provider. Optional Optional    
Scheduled Start Date Datetime If the batch has been scheduled, the expected start time is provided here. Optional Optional    
Created Date Datetime Indicates when the batch was created as recorded by the API provider. Optional Mandatory    
Approved Date Datetime Indicates when the batch was approved as recorded by the API provider. Optional Mandatory    
Completed Date Datetime Indicates when the batch was completed as recorded by the API provider. Optional Mandatory    
Rejections Count Integer Indicates the number of records that have been rejected, either during parsing or during final processing. Optional Optional    
Parsing Success Count Integer Indicates the number of records that have been parsed successfully. Optional Optional    
Completed Count Integer Indicates the number of records that have been successful completed. Optional Optional    
Transaction Data Reference Array Collection of Transactions that are to be processed Mandatory N/A Transactions  

Try it Out - Create a Batch Transaction

Try it Out - View a Batch Transaction

Try it Out - Update a Batch Transaction

Batch Rejections API

As described above, this API enables clients to retrieve information on all transactions that have either failed parsing or have failed to be completed. Only GET is supported. Format is:

batchtransactions/{Batch ID}/rejections

In order 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 10 to 60.
fromDateTime String DateTime Indicates the minimum date for which records should be returned.
toDateTime String DateTime Indicates the maximum date for which records should be returned.

Note that http response metadata is returned with each response that is paginated indicating the total number of records available and total number of records returned.

Batch Rejection Object Properties
Name Type Description Request Response Reference
Transaction Reference String Transaction Reference as assigned by the API provider. N/A Optional  
Date Rejected Datetime Date and time of the rejection. N/A Mandatory  
Debit Party Identifier Reference Array The debit party identifiers for the transaction as specific in the batch request. N/A` Mandatory Account Identifiers
Credit Party Identifier Reference Array The credit party identifiers for the transaction as specific in the batch request. N/A Mandatory Account Identifiers
Rejection Reason String The reason for the transaction request as indicated by the API provider. N/A Mandatory  
Requesting Organisation Transaction Reference String A reference provider by the requesting organisation that is to be associated with the transactions N/A Optional  

Try it Out - View Batch Rejections

Batch Completions API

This API lists all transactions that have successfully completed for a given batch. Only GET is supported. Format is:

batchtransactions/{Batch ID}/completions

In order 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 10 to 60.
fromDateTime String DateTime Indicates the minimum date for which records should be returned.
toDateTime String DateTime Indicates the maximum date for which records should be returned.

Note that http response metadata is returned with each response that is paginated indicating the total number of records available and total number of records returned.

Batch Completion Object Properties
Name Type Description Request Response Reference
Transaction Reference String Transaction Reference as assigned by the API provider. N/A Mandatory  
Date Completed Datetime Date and time indicating when the transaction was completed. N/A Mandatory  
Link String Provides a URL to the transaction resource. N/A Mandatory  
Debit Party Identifier Reference Array The debit party identifiers for the transaction as specific in the batch request. N/A` Mandatory Account Identifiers
Credit Party Identifier Reference Array The credit party identifiers for the transaction as specific in the batch request. N/A Mandatory Account Identifiers
Requesting Organisation Transaction Reference String A reference provider by the requesting organisation that is to be associated with the transactions N/A Optional  


 

Try it Out - View Batch Completions

Accounts

Identifying a Target Account

Two methods are providing for identifying an account – the multiple identifiers method and the MSISDN identifier method.

  • Multiple Identifiers Method

    There is no single industry-accepted method of uniquely identifying an account. There are numerous methods of identifying an account and the list of permitted identifiers can be found in the Account Identifiers section. Every Account API identifies the target account through the URI. As there can be multiple identifiers required to identify the target account, the URI uses a ‘$’ delimiter to separate each identifier. The format can be expressed as:

    /accounts/{accountIdentifier1}@{value1}${accountIdentifier2}@{value2}${accountIdentifier3}@{value3}
    
  • MSISDN Identifier Method

    In the scenario where MSISDN is the only identifier needed to uniquely identify an account, an alternate short URI is available:

    /accounts/msisdn/{value}

Supported Operations

The Accounts object can support various operations. A list of supported account resources is listed below:

  • /accounts/{Account Identifiers}/status. Returns the current status for an account. See the Accounts Status API for more information.
  • /accounts/{Account Identifiers}/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/{Account Identifiers}/balance. Returns the balances for the account. See the Account Balances API for more information.
  • /accounts/{Account Identifiers}/statemententries. Returns all statement entries for a given account. See the Statement Entries API for more information.
  • /accounts/{Account Identifiers}/bills. Returns all outstanding bills for a given account. See section the Bills API for more information.
  • /accounts/{Account Identifiers}/debitmandates. Allows the creation, updating and viewing of debit mandates for a given account. See Debit Mandates API for more information.
  • /accounts/{Account Identifiers}/links. Allows the creation, updating and viewing of account to account links for a given account. See Links API for more information.

Returning Transactions for an Account

It is possible to return a range of transactions for an account as per the following format:

/accounts/{Account Identifiers}/transactions.

In order 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 10 to 60.
fromDateTime String DateTime Indicates the minimum date for which records should be returned.
toDateTime String DateTime Indicates the maximum date for which records should be returned.

 

Note that all transactions will be returned in descending date created order. Also note that metadata is returned with each response that is paginated indicating the total number of records available.

The APIs

Account Status

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. URI format is:

/accounts/{Account Identifiers}/status
Name Type Description Request Response Validation
Account Status 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 an unregistered voucher creation. NA Mandatory Enumeration = available, unavailable, unregistered
Account Sub-Status String Property can be used to return a provider-specific status for the account. NA Optional  
LEI String Indicates the Legal Entity Identifier of the organisation holding the account. NA Optional Length = 20, Regular Expression (See Swagger Definition)

 

Try it Out - View Account Status

Balance

This API defines specific properties for returning balances associated with an account. URI format is:

/accounts/{Account Identifiers}/balance
Name Type Description Request Response Validation
Current Balance String The current outstanding balance on the account NA Optional Regular Expression – please refer to Swagger definition
Available Balance String Indicates the balance that is able to be debited for an account. This balance is only provided on some API provider systems. NA Optional Regular Expression – please refer to Swagger definition
Reserved Balance 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 Optional Regular Expression – please refer to Swagger definition
Uncleared Balance String Indicates the sum of uncleared funds in an account, i.e. those that are awaiting a credit confirmation. NA Optional Regular Expression – please refer to Swagger definition
Currency String Currency for all returned balances. NA Optional Enumeration = ISO Currency Codes
Account Status String Indicates a simplified 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 an unregistered voucher creation. NA Optional Enumeration = available, unavailable, unregistered

 

Try it Out - View Account Balance

Account Name

This API defines specific properties for returning account holder name information associated with an account. URI format is:

/accounts/{Account Identifiers}/accountname
Name Type Description Request Response Reference Validation
Account Name Reference A collection of properties detailing the name of the Primary Account Holder. NA Optional Name  
Account Status String Indicates a simplified 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 an unregistered voucher creation. NA Mandatory   Enumeration = available, unavailable, unregistered
LEI String Indicates the Legal Entity Identifier of the organisation holding the account. NA Optional   Length = 20, Regular Expression (See Swagger Definition)

Try it Out - View Account Name

Statement Entries

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 a statements, an account or a transaction must be specified. The URI format is as follows:

Statement Entries for an Account:

/accounts/{Account Identifiers}/statemententries

In order 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 10 to 60.
fromDateTime String DateTime Indicates the minimum date for which records should be returned.
toDateTime String DateTime Indicates the maximum date for which records should be returned.

Note that all statement entries will be returned in descending date created order. Also note that metadata is returned with each response that is paginated indicating the total number of records available.

Note that it is also possible to retrieve an individual statement entry as per the following:

/statemententries/{Transaction Reference}

Only GET (read) operations are supported for statement entries.

Name Type Description Request Response Reference Validation
Amount String Requested transaction amount. NA Mandatory   Regular Expression – please refer to Swagger definition
Currency String Currency of the requested transaction amount. NA Mandatory   Enumeration = ISO Currency Codes
Display Type 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 Optional    
Transaction Status String Indicates the status of the transaction as represented by the API provider. NA Mandatory    
Description Text String Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on the SMS and on the account statement. NA Optional    
Request Date DateTime The creation date and time of the transaction as supplied by the client. NA Optional    
Date Created DateTime Date and time when the transaction was created by the API Provider NA Optional    
Date Modified DateTime Date and time when the transaction modified by the API Provider NA Optional    
Transaction Reference String Unique reference for the transaction. This is returned in the response by API provider. NA Mandatory    
Transaction Receipt String Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. NA Optional    
Debit Party Identifier Reference Array A collection of key/value pairs that identify the debit. Keys include MSISDN and Wallet Identifier. NA Mandatory Account Identifiers  
Credit Party Identifier Reference Array A series of key/value pairs that identify the credit party. Keys include MSISDN and Wallet Identifier. NA Mandatory Account Identifiers  

Try it Out - View Account Statements

Bills

The Bills API is used to return all outstanding bills associated with an account. The main purpose of the object 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. The URI format is as follows:

/accounts/{Account Identifiers}/bills

In the scenario where MSISDN is the only identifier needed to uniquely identify an account, an alternate short URI is available:

/accounts/msisdn/{value}

Only GET (read) operations are permitted for the Bills object.

Name Type Description Request Response Reference Validation
Currency String Currency of the bill to be paid. NA Optional   Enumeration = ISO Currency Codes
Amount Due String Amount outstanding on the bill to be paid NA Optional   Regular Expression – please refer to Swagger definition
Due Date Date Date on which the Bill is due to be paid NA Optional    
Bill Reference String Reference number for the Bill that this payer can use when he/she wishes to pay NA Optional    
Minimum Amount Due String The minimum amount that is outstanding on the bill to be paid. NA Optional   Regular Expression – please refer to Swagger definition
Bill Description String Description of the bill that is to be paid. NA Optional    
Metadata Reference Array A collection of key/value pairs. These can be used to return additional information regarding the bill. NA Optional Metadata  

Try it Out - View Account Bills

Bill Payments

The Bills Payments API is used to pay a specific bill associated with an account. There is a choice of URI format as per below:

  • Full method of identifying a bill for which the payment is to be made:
    /accounts/{Account Identifiers}/bills/{Bill Reference}/payments
  • In the scenario where MSISDN is the only identifier needed to uniquely identify the bill account, use:
    /accounts/msisdn/{value}/bills/{Bill Reference}/payments
  • In the scenario where the Bill Payment reference can be used in isolation to uniquely identify the bill, use:
    /bills/{Bill Reference}/payments

 

Bill Payment Object Properties
Name Type Description Request Response Reference Validation
Currency String Currency of the amount that is being paid. Mandatory Mandatory   Enumeration = ISO Currency Codes
Paid Amount String Amount that is being paid. Mandatory Mandatory    
Customer Reference Date Textual reference provided by the customer paying the bill Optional Optional    
Supplementary Bill Reference Details Reference 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. Optional Optional Supplementary Bill References  

Try it Out - Create Bill Payment

Debit Mandates

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 payer would be able to take any amount. Due to the need to obtain explicit payer approval, requests for mandates are typically asynchronous in nature. Mandates can be created, changed and inactivated. The URI format is as follows:

Creation:

POST /accounts/{Account Identifiers}/debitmandates

 

Update

In order to update a debit mandate, a HTTP PATCH is used. Format is:

PATCH /accounts/{Account Identifiers}/debitmandates/{Mandate Reference}

 

Read:

GET /accounts/{Account Identifiers}/debitmandates/{Mandate Reference}

 

Debit Mandates Object

Name Type Description Request Response Reference Validation
Currency String Currency of the principal transaction amount. Optional Optional   Enumeration = ISO Currency Codes
Amount Limit String The maximum amount that can be taken by the Payee on a payment request Optional Optional    
Start Date Date Date on which the first payment is to be taken. Mandatory Mandatory    
End Date Date Date on which the final payment is to be taken. Optional Optional    
Number of Payments Number Indicates the number of consecutive payments that are to be taken. Optional Optional    
Frequency Type String Indicates the frequency for which payments will be taken from the payers account. Optional Optional   Enumeration = Frequency
Mandate Status String Indicates the status of the Mandate as held in the API Provider system Optional Optional   Enumeration = active, inactive
Mandate Reference String Unique reference provided by the API Provider for the mandate. Optional Mandatory    
Request Date DateTime The creation date and time of the transaction as supplied by the client. Mandatory Mandatory    
Date Created DateTime Date and time when the debit mandate was created by the API Provider NA Optional    
Date Modified DateTime Date and time when the debit mandate was modified by the API Provider NA Optional    

Try it Out - Create Debit Mandate

Try it Out - View Debit Mandate

Links API

The Links API is used to establish a link between two separate accounts on the client and provider’s systems. The API can be used for example to link a mobile wallet account to an MFI 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.

In order to identify the accounts that are to be linked, the target account is specified in the URI whereas the source account is specific in the link object.

The URI format is as follows:

Creation:

POST /accounts/{Target Account Identifiers}/links

 

Update:

In order to update a Link (status and/or mode), a HTTP PATCH is used. Format is:

PATCH /accounts/{Target Account Identifiers}/links/{Link Reference}

 

Read:

GET /accounts/{Target Account Identifiers}/links/{Link Reference}

 

Link Object

Name Type Description Request Response Reference Validation
Link Reference String Indicates the Link reference. This enables a linked account to be uniquely identified. NA Mandatory    
Link Status String Indicates the status of the Link. Mandatory Mandatory   Enumeration = active, inactive
Link Mode String Indicates the mode of operation support for the Link. If not populated, then default value it ‘Both’. Optional Optional   Enumeration = push, pull, both
Source Account Identifier Reference Array A series of key/value pairs that identify the source account. Keys include MSISDN and Wallet Identifier. Mandatory Mandatory Account Identifiers  

Try it Out - Create a Link

Try it Out - View a Link

Try it Out - Update a Link

Quotations

The quotations API is used to obtain one or multiple quotes for a mobile money customer that wishes to send money internationally. The production of a quote typically involves obtaining the Forex rate and any additional fees that will be levied on the sending customer. Normally a request is made for a quotation by the requesting mobile money system (also known as the Sending Service Provider) in response to a customer request. The quotation is then provided to an IMT hub (also known as a Wholesale Service Provider) which is typically responsible for performing sender (and possibly receiver) AML checks as well as obtaining a Forex rate. The quotation is calculated and returned to the requesting mobile money system. If the customer is satisfied with the quotation, then he will initiate an International Transfer transaction.

The quotations object supports:

Creation of a quotation:

POST /quotations

View a quotation:

GET /quotations/{Quotation Reference}

Quotations Object

CLick here to view the Swagger API Definition

Name Type Description Request Response Reference Validation
Quotation Reference String Unique reference for the Quotation as provided by the API Provider NA Mandatory    
Quotation Status String Indicates the creation state of the quotation. NA Optional   Enumeration = pending, rejected, completed
Request Date DateTime The creation date and time of the transaction as supplied by the client. Mandatory Mandatory    
Date Created DateTime Date and time when the transaction was created by the API Provider NA Optional    
Date Modified DateTime Date and time when the transaction was modified by the API Provider NA Optional    
Debit Party Identifier Reference Array A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier. Mandatory Mandatory Account Identifier  
Credit Party Identifier Reference Array A series of key/value pairs that enable the credit party to be identified. Keys include MSISDN and Wallet Identifier. Mandatory Mandatory Account Identifier  
Sender KYC Reference A collection of properties detailing the KYC of the transaction Sender, typically used for International Transfers. Optional Optional KYC Information  
Recipient KYC Reference A collection of properties detailed the KYC of the transaction Recipient, typically used for International Transfers. Optional Optional KYC Information  
Request Amount String Requested quotation amount. Mandatory Mandatory    
Request Currency String Currency of the requested quotation amount. Mandatory Mandatory   Enumeration = ISO Currency Codes
Chosen Delivery Method String The delivery method chosen by the sending end user as the specific delivery method to be used in the quotes received. Optional Optional   Enumeration = Delivery Method
Available Delivery Methods String Array Delivery Methods that are possible for the intended recipient. NA Optional   Enumeration = Delivery Method
Quotes Reference Array A collection of quotes. A quote can be received from a single receiving payment service provider or from multiple providers. Optional Optional Quotes  
Sender Blocking Reason String The reason for blocking the quotation, based on AML checks on the sender Optional Optional    
Recipient Blocking Reason String The reason for blocking the quotation, based on AML checks on the recipient Optional Optional    
Metadata Reference Array A collection of key/value pairs. These can be used to populate additional quotation properties. Optional Optional Metadata Object  

Try it Out - Create a Quotation

Try it Out - View a Quotation

Try it Out - Update a Quotation

Supporting Objects

International Transfer Information Object

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

Name Type Description Request Response Validation
Country of Origin String The originating country of the transaction, i.e. the country where the transaction commenced. Mandatory Mandatory Enumeration = ISO Country Codes
Quotation Reference String Reference for the quotation that was provider to the sender. (refer to Quotations API for more information). Optional Optional  
Quote ID String The specific quote associated with the quotation (refer to Quotes object for more information). Optional Optional  
Receiving Country String Destination Country of international remittance Optional Optional  
Purpose of Remittance String Property providing a description of the reason for the international remittance. Optional Optional  
Relationship with Sender String Indicates the relationship (if any) between the sender and the receiver Optional Optional  
Delivery Method to Use String The recipient delivery method as chosen by the sender Optional Optional Enumeration = Delivery Method Types
Sender Blocking Reason String The reason for blocking the transaction, based on AML checks on the sender NA Optional  
Recipient Blocking Reason String The reason for blocking the transaction, based on AML checks on the recipient NA Optional  

Name Object

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

Name Type Description Request Response
Title String The given title of the KYC subject, e.g. Mr, Mrs, Dr. Optional Optional
First Name String First name (also referred to as given name) of the KYC subject. Optional Optional
Middle Name String Middle Name of the KYC subject. Optional Optional
Last Name String Surname (also referred to as last or family name) of the KYC subject. Optional Optional
Full Name String The full name of the KYC subject. Optional Optional
Native Name String The full name expressed as in the native language Optional Optional
 

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 Country is mandatory.

Name Type Description Request Response Validation
Address Line 1 String First line of the address. Optional Optional  
Address Line 2 String Second line of the address. Optional Optional  
Address Line 3 String Third line of the address. Optional Optional  
City String City/Town Optional Optional  
StateProvince String State or Province Optional Optional  
PostalCode String Postal Code Optional Optional  
Country String Country Optional Optional Enumeration = ISO Country Codes

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

ISO Country Codes

The two-character alphabetic code for country as defined by ISO 4217 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

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 either 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 either at a physical agent or via ATM
 

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.

Name Type Description Request Response Reference Validation
Nationality String Nationality of the KYC subject. Optional Optional   Enumeration = ISO Country Codes
Date of Birth Date Birth date of the KYC subject. Optional Optional    
Occupation String Occupation of the KYC subject. Optional Optional    
Employer Name String Employer Name of the KYC subject. Optional Optional    
Contact Phone String Contact phone number (mobile or landline) of the KYC subject. Phone number to be provided in international format as per ITU E.123. Optional Optional   Regular Expression to validate against ITU E.123 Refer to Swagger definition for more information.
Gender String Gender of the KYC Object. Optional Optional   Length=1, Enumeration = (m)ale, (f)emale, (u)nspecified
Id Document Reference Array An array of properties containing the forms of identification that are associated with the subject. Optional Optional Id Document  
Postal Address Reference A collection of properties that details the postal address of the KYC subject. Optional Optional Address  
KYC Subject Name Reference Refers to the name properties for the KYC subject Optional Optional Name  
Email Address String Email address of the KYC subject Optional Optional    
Birth Country String The country of birth of the KYC subject Optional Optional   Enumeration = ISO Country Codes

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.

Name Type Description Request Response
Key String Identifies the type of additional property. Mandatory Mandatory
Value String Identifies the value of the additional property. Mandatory Mandatory

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 Short Code, Account Number, Agent/Merchant Short Code 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.

Name Type Description Request Response Validation
Key String Provides the account identifier type. Mandatory Mandatory Enumeration = Account Identifiers
Value String Provides the account identifier type value. Mandatory Mandatory  

Account Identifiers Enumerations

The Account Identifier enumeration lists all possible means to identify a target account and for transactions, the debit and/or credit party. Identifiers can be combined if necessary to provide a unique identifier for the target account.

Code Short Desc 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 ranks 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 or company name/number for a bill payment.
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 Mobile Number of the account holder. Should conform to ITU E.123.
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 Short 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.

Delivery Methods

When a customer requests and international transfer quotation they are able to specify their preferred method of delivery of the transfer to the recipient. Acceptable delivery methods are provided below.

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

ID Types

The ID Types enumeration lists accepted identification types. Due to the wide international variation in accepted types of identification, a catch-all type of ‘OtherID’ has also been defined.

ID Type Description
passport Payment of bill from a business for goods and/or services.
nationalregistration National Registration Number
otherid 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

Frequency Types

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

weekly: Payment will be taken weekly
fortnight: Payment will be take every two weeks
monthspecificdate: Payment to be taken on a specific date every month
2months: Payment to be taken every two months
3months: Payment to be taken every three months
4months: Payment to be taken every four months
6months: 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

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.

Name Type Description Request Response
Payment Reference Type String Identifies the type of the additional payment reference. Mandatory Mandatory
Payment Reference Value String Identifies the value of the additional payment reference. Mandatory Mandatory
 

Quotes

The quotes object defines the properties associated with international remittance quotes.

Name Type Description Request Response Validation
QuoteID String The unique ID for this quote NA Mandatory  
QuoteExpiryTime DateTime The timestamp when the quote will expire NA Optional  
Receiving Service Provider String The name of the RSP, i.e. the provider that the quote is associated with. NA Optional  
Sending Amount String Requested quotation amount as supplied by the sender. NA Mandatory Regular Expression – please refer to Swagger definition
Sending Currency String Currency of the requested quotation amount. NA Mandatory Enumeration = ISO Currency Codes
Receiving Amount String The total amount as it will be received by the receiving end user. NA Mandatory Regular Expression – please refer to Swagger definition
Receiving Currency String The currency of the quote. NA Mandatory Enumeration = ISO Currency Codes
FXRate String The conversion rate applicable between the sending and the receiving currency for the requested transaction NA Mandatory Regular Expression – please refer to Swagger definition
Delivery Method String The delivery method that is applicable to the quotation NA Optional Enumeration = Delivery Method