^

Accounts APIs

The Accounts APIs are used to view properties associated with an account resource. Types of account include mobile wallets, financial institution accounts and utility accounts (e.g. for electricity).

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

Click here to view the Swagger API Definition

Accounts 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 RequestResponse 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. NAMandatory Enumeration = available, unavailable, unregistered
Account Sub-Status String Property can be used to return a provider-specific status for the account. NAOptional
LEI String Indicates the Legal Entity Identifier of the organisation holding the account. NAOptional 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 RequestResponse Validation
Current Balance String The current outstanding balance on the account NAOptional 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. NAOptional 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. NAOptional 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. NAOptional Regular Expression – please refer to Swagger definition
Currency String Currency for all returned balances. NAOptional 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. NAOptional 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 RequestResponse Reference Validation
Account Name Reference A collection of properties detailing the name of the Primary Account Holder. NAOptional 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. NAMandatory Enumeration = available, unavailable, unregistered
LEI String Indicates the Legal Entity Identifier of the organisation holding the account. NAOptional 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 RequestResponse Reference Validation
Amount String Requested transaction amount. NAMandatory   Regular Expression – please refer to Swagger definition
Currency String Currency of the requested transaction amount. NAMandatory   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. NAOptional    
Transaction Status String Indicates the status of the transaction as represented by the API provider. NAMandatory    
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. NAOptional  
Request Date DateTime The creation date and time of the transaction as supplied by the client. NAOptional    
Date Created DateTime Date and time when the transaction was created by the API Provider NAOptional    
Date Modified DateTime Date and time when the transaction modified by the API Provider NAOptional    
Transaction Reference String Unique reference for the transaction. This is returned in the response by API provider. NAMandatory    
Transaction Receipt String Transaction receipt number as notified to the parties. This may differ from the Transaction Reference. NAOptional    
Debit Party Identifier Reference Array A collection of key/value pairs that identify the debit. Keys include MSISDN and Wallet Identifier. NAMandatory Account Identifiers  
Credit Party Identifier Reference Array A series of key/value pairs that identify the credit party. Keys include MSISDN and Wallet Identifier. NAMandatory 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 RequestResponse Reference Validation
Currency String Currency of the bill to be paid. NAOptional   Enumeration = ISO Currency Codes
Amount Due String Amount outstanding on the bill to be paid NAOptional   Regular Expression – please refer to Swagger definition
Due Date Date Date on which the Bill is due to be paid NAOptional    
Bill Reference String Reference number for the Bill that this payer can use when he/she wishes to pay NAOptional    
Minimum Amount Due String The minimum amount that is outstanding on the bill to be paid. NAOptional   Regular Expression – please refer to Swagger definition
Bill Description String Description of the bill that is to be paid. NAOptional    
Metadata Reference Array A collection of key/value pairs. These can be used to return additional information regarding the bill. NAOptional 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 RequestResponse Reference Validation
Currency String Currency of the amount that is being paid. MandatoryMandatory   Enumeration = ISO Currency Codes
Paid Amount String Amount that is being paid. MandatoryMandatory    
Customer Reference Date Textual reference provided by the customer paying the bill OptionalOptional    
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. OptionalOptional 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 RequestResponse Reference Validation
Currency String Currency of the principal transaction amount. OptionalOptional   Enumeration = ISO Currency Codes
Amount Limit String The maximum amount that can be taken by the Payee on a payment request OptionalOptional    
Start Date Date Date on which the first payment is to be taken. MandatoryMandatory    
End Date Date Date on which the final payment is to be taken. OptionalOptional    
Number of Payments Number Indicates the number of consecutive payments that are to be taken. OptionalOptional    
Frequency Type String Indicates the frequency for which payments will be taken from the payers account. OptionalOptional   Enumeration = Frequency
Mandate Status String Indicates the status of the Mandate as held in the API Provider system OptionalOptional   Enumeration = active, inactive
Mandate Reference String Unique reference provided by the API Provider for the mandate. OptionalMandatory    
Request Date DateTime The creation date and time of the transaction as supplied by the client. MandatoryMandatory    
Date Created DateTime Date and time when the debit mandate was created by the API Provider NAOptional    
Date Modified DateTime Date and time when the debit mandate was modified by the API Provider NAOptional    

Try it Out - Create Debit Mandate

Try it Out - View Debit Mandate



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


Supporting Objects

Name Object

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

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


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



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



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 RequestResponse
Key String Identifies the type of additional property. MandatoryMandatory
Value String Identifies the value of the additional property. MandatoryMandatory


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 RequestResponse
Payment Reference Type String Identifies the type of the additional payment reference. MandatoryMandatory
Payment Reference Value String Identifies the value of the additional payment reference. MandatoryMandatory


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, Wallet Identifier and Payment Reference (used for Bill Payments). 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 RequestResponse Validation
Key String Provides the account identifier type. MandatoryMandatory Enumeration = Account Identifiers
Value String Provides the account identifier type value. MandatoryMandatory  


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.