^

Quotations APIs

Introduction

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}


The APIs

CLick here to view the Swagger API Definition

Quotations Object

Name Type Description RequestResponse Reference Validation
Quotation Reference String Unique reference for the Quotation as provided by the API Provider NAMandatory    
Quotation Status String Indicates the creation state of the quotation. NAOptional   Enumeration = pending, rejected, completed
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 transaction was created by the API Provider NAOptional    
Date Modified DateTime Date and time when the transaction was modified by the API Provider NAOptional    
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. MandatoryMandatory 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. MandatoryMandatory Account Identifier  
Sender KYC Reference A collection of properties detailing the KYC of the transaction Sender, typically used for International Transfers. OptionalOptional KYC Information  
Recipient KYC Reference A collection of properties detailed the KYC of the transaction Recipient, typically used for International Transfers. OptionalOptional KYC Information  
Request Amount String Requested quotation amount. MandatoryMandatory    
Request Currency String Currency of the requested quotation amount. MandatoryMandatory   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. OptionalOptional   Enumeration = Delivery Method
Available Delivery Methods String Array Delivery Methods that are possible for the intended recipient. NAOptional   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. OptionalOptional Quotes  
Sender Blocking Reason String The reason for blocking the quotation, based on AML checks on the sender OptionalOptional    
Recipient Blocking Reason String The reason for blocking the quotation, based on AML checks on the recipient OptionalOptional    
Metadata Reference Array A collection of key/value pairs. These can be used to populate additional quotation properties. OptionalOptional Metadata Object  

Try it Out - Create a Quotation

Try it Out - View a Quotation

Try it Out - Update a Quotation


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


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 RequestResponse Validation
Address Line 1 String First line of the address. OptionalOptional  
Address Line 2 String Second line of the address. OptionalOptional  
Address Line 3 String Third line of the address. OptionalOptional  
City String City/Town OptionalOptional  
StateProvince String State or Province OptionalOptional  
PostalCode String Postal Code OptionalOptional  
Country String Country OptionalOptional 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



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 RequestResponse Reference Validation
Nationality String Nationality of the KYC subject. OptionalOptional   Enumeration = ISO Country Codes
Date of Birth Date Birth date of the KYC subject. OptionalOptional    
Occupation String Occupation of the KYC subject. OptionalOptional    
Employer Name String Employer Name of the KYC subject. OptionalOptional    
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. OptionalOptional   Regular Expression to validate against ITU E.123 Refer to Swagger definition for more information.
Gender String Gender of the KYC Object. OptionalOptional   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. OptionalOptional Id Document  
Postal Address Reference A collection of properties that details the postal address of the KYC subject. OptionalOptional Address  
KYC Subject Name Reference Refers to the name properties for the KYC subject OptionalOptional Name  
Email Address String Email address of the KYC subject OptionalOptional    
Birth Country String The country of birth of the KYC subject OptionalOptional   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 RequestResponse
Key String Identifies the type of additional property. MandatoryMandatory
Value String Identifies the value of the additional property. 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 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 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.


Delivery Method

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



Quotes

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

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