Introduction


Purpose


The purpose of this document is to describe the GSMA interfaces available on the TerraPay network and the associated services and transaction flows.


Scope


The scope of this document is to give a brief explanation on how the GSMA APIs are integrated on the TerraPay network and how partners can use the GSMA APIs to integrate with TerraPay. Reference links will be provided whereever applicable for a more detailed information on the GSMA APIs.


Audience


This document is to be used by

  • TerraPay Integrations technical team
  • Partner Integrations technical team


Acronyms and Abbreviations


AML Anti Money Laundering
CFT Counter Financing of Terrorism
JSON JavaScript Object Notation
XML Extended Markup Language
HTTPS Secure Hyper Text Transfer Protocol
POC Proof of Concept
TPS Transactions Per econd
SOAP Simple Object Access Protocol
VPN Virtual Private Network
S2S Site to Site
MNO Mobile Network Operator
MTO Money Transfer Operator
MMO Mobile Money Operator
FOREX Foreign Exchange Rate
SRC Source
DST Destination
MSISDN Mobile Station International Subscriber Directory Number
Bank A/C Bank Account
IBAN International Bank Account Number
IFSC Indian Financial System Code
SWIFT Society of Worldwide Interbank Financial Telecommunication
SEPA Single Euro Payments Area
BIC Bank Identifier Code
KYC Know Your Customer
MNP Mobile number portability
AWS Amazon Web Services
DMZ De Militarized Zone
RDS Relational Database Service (AWS)
REST REpresentational State Transfer
MNP Mobile Number Portability
GMT Greenwich Mean Time
GSMA GSM Association
LEI Legal Entity Identifier

Assumptions


  1. Partner system will provide and manage the necessary interfaces for the subscriber of the partner to access the services of TerraPay.
  2. TerraPay system will integrate directly with the partner system only.
  3. The sender is a registered subscriber on the sending partner system.
  4. The beneficiary is a registered subscriber on the receiving partner system.
  5. Registered subscriber here meaning the partner is able to authenticate the subscriber with valid KYC information.
  6. Connectivity between TerraPay systems and partner systems is over a secure S2S VPN tunnel.
  7. Partner system will use HTTPS/JSON as an interface for GSMA based API integrations with TerraPay system.
  8. TerraPay will provide a secure SSL certificate to use for APIs connecting into the TerraPay system.
  9. Partner will provide a secure SSL certificate to use for APIs connecting into the partner system.
  10. To guarantee a good end-user experience requests sent to the partner system are expected to reply within 500ms. The same will be guaranteed from the TerraPay system.
  11. All timestamps handled by the TerraPay system is in GMT.


Connectivity, Staging & Production


TerraPay systems are hosted on AWS across regions. Partners connecting to TerraPay will be connected to one of these regions based on the proximity of the partner to a region. This region will then be the primary setup and the one other region will serve as the GR setup for the partner.

All partners will be provided connectivity to the TerraPay system over a secure VPN tunnel. The secure VPN will be established to both the Primary as well as the GR setup. Each setup will have two VPN tunnels, an active and standby.

All API interfaces between TerraPay and the partner will be over HTTPS. TerraPay will provide a SSL certificate for all inbound APIs. The partner will have to provide a SSL certificate for all outbound APIs.

All partners will integrate into TerraPay's EIG (External Interface Gateway) systems which are hosted on the DMZ (De Militarized Zone) of the TerraPay network. For integration testing all access to inbound and outbound APIs will be provided on the TerraPay staging system. Once all API validations are through then these will be migrated to live production servers.


Services


The services offered by the TerraPay system can be broadly classified as:

  1. Remit to Mobile
  2. Remit to Bank


Remit to Mobile


This service enables the sender to send money instantly to a beneficiary mobile number. The money is credited to a payment instrument associated with the beneficiary's mobile number. This could be a mobile operator wallet, a third party provider wallet, a bank wallet or even a bank account that is mapped to the mobile number. TerraPay automatically routes the transaction to the availble payment instrument and also in some cases allows the beneficiary to choose the payment instrument in which he wishes to receive the funds.

The sender can initiate the money transfer from a wallet or bank account.




Remit to Bank


This service enables the sender to send money to a beneficiary bank account.
The sender can initiate the money transfer from a wallet, bank account or by cash over the counter at a partner agent outlet.



GSMA APIs


This section introduces the set of GSMA APIs that are implemented by TerraPay and is available for integration with partners. These APIs cater to the services offered by TerraPay as described above.
For more detailed information on the GSMA API suite please refer mmapai.gsma.com

Basic Transaction Steps

  • Sender initiates a transaction from,
    • A registered Mobile Wallet
    • An active Bank Account
  • Sender provides the beneficiary mobile number that will receive the funds.
  • In case of Remit to Bank, the sender provides the beneficiary bank account details that will receive funds.
  • Sending partner forwards the beneficiary mobile number/bank account to TerraPay to validate if the beneficiary can receive funds.
  • TerraPay validates if the beneficiary mobile number is assoicated with a valid payment instrument and if that instrument is active and can receive funds.
  • In case of Remit to beneficiary bank account, TerraPay will validate if the bank is supported and the details provided are valid syntactically.
  • Sender then intiates a request of quote. Sender provides the amount to be transferred. TerraPay will process the quote and provide the sender with the forex rate and the amount the beneficiary will receive.
  • Sender then confirms the transaction.
  • TerraPay then validates the transaction and credits the amount to beneficiary mobile number or bank account
  • **Note - Both sender and beneficiary KYC has to be provided by the sending and receiving partners to TerraPay in order to perform AML validations. This information has to be mandatorily provided via the API calls.
Note: All API calls to the TerraPay Network should include the following HTTP Headers
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "YYYY-MM-DD HH:mm:ss"
X-ORIGINCOUNTRY: "Country Code in which the transaction is created. ISO Alpha 2 standard"

X-USERNAME, X-PASSWORD values will be shared with the Partner during onboarding on test and production environment seperately.
Username and Password is always case-insensitive.
X-PASSWORD must be SHA256 hash encoded as part of API request.

Inbound APIs


The Inbound APIs will be used by sending partners to integrate with TerraPay to send below request.

View Account Status


GSMA reference https://mmapi.gsma.com/accounts/index.html#sub1

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

View Account Status of a Mobile Wallet

URL: https://uat-connect.terrapay.com:21211/eig/gsma/accounts/msisdn/{msisdn}/status?bnv={beneficiaryName}&provider={provider}&snv={senderName}

HTTP Request
GET /eig/gsma/accounts/msisdn/+234xxxxxxxxx/status?bnv=John%20Smith&provider=23401&snv=David%20Robinson HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY: "US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "status":"available", 
 "subStatus":"6000:Beneficiary MSISDN Validation Success", 
 "lei":""
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.", 
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"6008", 
    "errorDescription":"Beneficiary name does not match", 
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

                                                            


Request Parameters

Parameter name Description Data Type Requirement Field Length
msisdn Beneficiary MSISDN with country code. This corresponds to the mobile wallet to which funds are to be transferred. Eg. +91xxxxxxxxxx String Mandatory 10-18
bnv Full KYC name of the beneficiary as registered with the wallet provider. String Mandatory 1-50
snv Full name of the sender as per KYC Id document. String Optional 1-50
provider This is a code that indicates the Mobile Operator to which the transaction is to be sent.
This field is conditional.If not set, TerraPay will automatically find the wallet operator that the beneficiary MSISDN belongs to and will validate the MSISDN.
If set, then TerraPay will validate the MSISDN against the operator specified. In case the provider code does not match the actual operator the validation will be rejected.
NOTE: Mandatory for Bangledsh & Philippines termination.
            Optional for other countries.
Numeric Conditional 5

View Account Status of a Bank Account

URL: https://uat-connect.terrapay.com:21211/eig/gsma/accounts/{accountId}/status?bnv={beneficiaryName}&bankcode={bankCode}&bankname={bankName}&country={countryCode}&msisdn={msisdn}&provider={provider}&snv={senderName}

HTTP Request
GET /eig/gsma/accounts/232698745623/status?bnv=John%20Smith&bankcode=CBKEKENX&bankname=CENTRAL%20BANK%20OF%20KENYA&country=US&provider=2549008&snv=David%20Robinson HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY: "US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "status":"available", 
 "subStatus":"6000:Beneficiary Bank Account Validation Success", 
 "lei":"", 
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.", 
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"6008", 
    "errorDescription":"Beneficiary name does not match", 
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

                                                            

Request Paramters

Parameter name Description Data Type Requirement Field Length
accountId Beneficiary Bank Account or IBAN Number as applicable in the destination country for receiving funds. Eg. 2365417895. String Mandatory 5-50
bnv Full KYC name of the beneficiary as registered with the bank. String Mandatory 1-50
snv Full name of the sender as per KYC Id document. String Optional 1-50
bankcode Bank Code as required in the destination Country. It can be one of
IFSC Code
Routing Code
Swift BIC
This code is specific to bank integration in each country and may be mandatory in certain destination countries
String Conditional 4-25
bankname Full name of the beneficiary bank String Mandatory 4-60
country ISO Alpha 2 country code of the destination country. Eg. NG for Nigeria String Mandatory 2
msisdn Beneficiary mobile number with country code in countries where is it mandatory for bank transfers. Eg. +91xxxxxxxxxx
NOTE: Mandatory for Nigeria & Vietnam termination.
            Optional for other countries.
String Conditional 10-18
provider This is a code that indicates the bank to which the transaction is to be sent.
This field is conditional.If not set, then TerraPay will resolve the bank based on bankCode. If the bankCode is incorrectly provided, then the bank will be resolved based on Bank Name (Should match exactly as per the bank list shared by TerraPay). If these parameters do no match then the transaction will be rejected.
If set, then TerraPay will resolve the bank based on the provider code.
NOTE: Mandatory for Bangledsh termination.
            Optional for other countries.
Numeric Conditional 7-12

Response Parameters

Parameter name Description Data Type Validation
status 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. String Enumeration = available, unavailable, unregistered
subStatus Property can be used to return a provider-specific status for the account. String
lei Indicates the Legal Entity Identifier of the organisation holding the account. String Length = 20, Regular Expression

Create Quotation


GSMA reference https://mmapi.gsma.com/quotes/index.html#sub1

The quotations API is used to obtain one or multiple quotes for a mobile money customer that wishes to send money internationally. URI format is:

/quotations

Create a Quotation to Mobile Wallet

URL: https://uat-connect.terrapay.com:21211/eig/gsma/quotations

HTTP Request
POST /eig/gsma/quotations HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

{
"requestDate": "2017-05-03 11:00:00",
   "debitParty": [
    {
      "key": "msisdn",
      "value": "+4491509874561"
    }
  ],
   "creditParty": [
    {
      "key": "msisdn",
      "value": "+25691508523697"
    }
  ],
  "requestAmount": "100",
  "requestCurrency": "EUR",
   "quotes": [
    {
      "sendingCurrency": "EUR",
      "receivingCurrency": "UGX"
    }
  ]
 }

HTTP Response - Success
HTTP/1.1 201 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
"requestDate": "2017-05-03 11:00:00",
   "debitParty": [
    {
      "key": "msisdn",
      "value": "+4491509874561"
    }
  ],
   "creditParty": [
    {
      "key": "msisdn",
      "value": "+25691508523697"
    }
  ],
  "requestAmount": "100",
  "requestCurrency": "EUR",
   "quotes": [
    {
      "quoteId": "QT037fQXs3LGWXea4",
      "quoteExpiryTime": "2017-05-03 11:28:00",
      "sendingAmount": "100.000000",
      "sendingCurrency": "EUR",
      "receivingAmount": "365217",
      "receivingCurrency": "UGX",
      "fxRate": "3652.173913"
    }
  ],
  "quotationReference": "QT037fQXs3LGWXea4",
  "quotationStatus": "2000:Quote Success"
 }

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.",
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"2001", 
    "errorDescription":"Source amount is invalid",
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"2003", 
    "errorDescription":"Failed to get Forex rate",
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

                                                    

Create a Quotation to Bank Account

URL: https://uat-connect.terrapay.com:21211/eig/gsma/quotations

HTTP Request
POST /eig/gsma/quotations HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

{
"requestDate": "2017-05-03 11:00:00",
   "debitParty": [
    {
      "key": "msisdn",
      "value": "+4491509874561"
    }
  ],
   "creditParty": [
    {
      "key": "msisdn",
      "value": "+25691508523697"
    },
    {
      "key": "bankaccountno",
      "value": "2356915085237"
    },
    {
      "key": "receivingCountry",
      "value": "NG"
    }
  ],
  "requestAmount": "100",
  "requestCurrency": "EUR",
   "quotes": [
    {
      "sendingCurrency": "EUR",
      "receivingCurrency": "UGX"
    }
  ]
 }

HTTP Response - Success
HTTP/1.1 201 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
"requestDate": "2017-05-03 11:00:00",
   "debitParty": [
    {
      "key": "msisdn",
      "value": "+4491509874561"
    }
  ],
   "creditParty": [
    {
      "key": "msisdn",
      "value": "+25691508523697"
    },
    {
      "key": "bankaccountno",
      "value": "2356915085237"
    },
    {
      "key": "receivingCountry",
      "value": "NG"
    }
  ],
  "requestAmount": "100",
  "requestCurrency": "EUR",
   "quotes": [
    {
      "quoteId": "QT037fQXs3LGWXea4",
      "quoteExpiryTime": "2017-05-03 11:28:00",
      "sendingAmount": "100.000000",
      "sendingCurrency": "EUR",
      "receivingAmount": "365217",
      "receivingCurrency": "UGX",
      "fxRate": "3652.173913"
    }
  ],
  "quotationReference": "QT037fQXs3LGWXea4",
  "quotationStatus": "2000:Quote Success"
 }

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.",
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"2001", 
    "errorDescription":"Source amount is invalid",
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"2003", 
    "errorDescription":"Failed to get Forex rate",
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

                                                    

Request Parameters

Parameter name Description Data Type Requirement Field Length
requestDate The creation date and time of the transaction as supplied by the client in YYYY-MM-DD HH:mm:ss DateTime Mandatory 19
requestAmount Requested quotation amount with precision of 2 decimal places String Mandatory 10,2
requestCurrency Currency of the requestAmount provided in ISO 4217 format. Eg. EUR.
If the requestCurrency is the source currency, then the requestAmount is taken as what the sender will pay and the quote is calculated in the destination currency and the quote amount returned will be what the beneficiary will receive.
If the requestCurrency is the destination currency, then the requestAmount is taken as what the beneficiary has to receive and the quote is calculated in source currency and the quote amount returned will be what the sender has to pay. (Reverse Quote).
String Mandatory 3
debitParty:
key msisdn String Optional 6
value Sender Mobile Number with country code. Eg.+91xxxxxxxxxx String Optional 10-18
creditParty:
Key msisdn String Conditional 6
Value Beneficiary Mobile Number with country code. Eg.+91xxxxxxxxxx. String Optional - For Bank Accounts
Mandatory - For Mobile Wallet
10-18
Key bankaccountno String Conditional 13
Value Beneficiary Bank Account or IBAN Number as applicable in the destination country for receiving funds. Eg. 2365417895.
This key/value pair is optional if the transfer is to a mobile wallet.
String Mandatory - For Bank Accounts
Optional - For Mobile Wallet
5-50
Key receivingCountry String Conditional 16
Value Destination Country. Eg. NG.
This key/value pair is optional if the transfer is to a mobile wallet.
String Mandatory - For Bank Accounts
Optional - For Mobile Wallet
5-50
quotes:
sendingCurrency Currency of the debitor in ISO 4217 format. Eg. EUR String Mandatory 3
receivingCurrency Currency of the creditor in ISO 4217 format. Eg. NGN String Mandatory 3

Create quotation response parameter list:

Parameter name Description Data Type
requestDate Timestamp as sent by the partner in the request API String
requestAmount Request Amount as sent by the partner in the request API String
requestCurrency Request currency as sent by the partner in the request API String
debitParty:
key msisdn String
value Sender Mobile Number as sent by the partner in the request API String
creditParty:
key msisdn String
value Beneficiary Mobile Number as sent by the partner in the request API String
key bankaccountno String
value Beneficiary bank account details as sent by the partner in the request API String
key receivingCountry String
value Destination country as sent by the partner in the request API String
quotes: Has one or many quotations. Sending partner to choose the applicable quote required and use the quoteId reference during the transaction. Eg. There could be two quotations, one with better rate but less expiry time(5 minutes) and the other with lower rate but more expiry time (1 day). Sending partner can choose which rate to apply based on when they will be able to send the transaction.
quoteId The unique ID for this quote provided by the forex provider.This id will be used by partner as part of transaction request. String
quoteExpiryTime The timestamp when the quote will expire. This is in partner local time based on the origin country of transaction String
sendingAmount Amount payable by the sender String
sendingCurrency Currency in which the sender will pay the sending amount String
receivingAmount Amount that the beneficiary will receive String
receivingCurrency Currency in which the beneficiary will receive funds String
fxRate Foreign Exchange rate applied on the quote including all markups String
quotationReference TerraPay Quote Reference String
quotationStatus Status of the quotation request. Format is ErrorCode:ErrorMessage String

Create A Transaction


GSMA reference https://mmapi.gsma.com/transactions/index.html#sub1

The Transactions API is used for all operations involving mobile money financial transactions. URI format is:

/transactions

Create a transaction to a Mobile Wallet

URL: https://uat-connect.terrapay.com:21211/eig/gsma/transactions

HTTP Request
POST /eig/gsma/transactions HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "descriptionText": "Gift for my brother",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "provider": "23401",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+33472034605"
    } 
  ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    }
  ],
   "senderKyc": {
     "nationality": "FR",
     "dateOfBirth": "1986-06-28",
     "gender": "M",
     "idDocument": [
      {
         "idType": "nationalidcard",
         "idNumber": "123456789",
         "issueDate": "2003-09-26",
         "expiryDate": "2033-09-26",
         "issuerCountry": "FR"
      }
    ],
     "postalAddress": {
       "addressLine1": "49 ",
       "addressLine2": "park street",
       "addressLine3": "walton's road",
       "city": "Lyon",
       "stateProvince": "Lyon",
       "postalCode": "123456",
       "country": "FR"
    },
     "subjectName": {
       "title": "Mr.",
       "firstName": "Einstein",
       "middleName": "James",
       "lastName": "Bela",
       "fullName": "Einstien James Bela"
    }
  },
    "recipientKyc":
    {
     "subjectName": {
      "firstName": "John",
       "lastName": "Smith",
       "fullName": "John Dave Smith"
    }
    },
   "internationalTransferInformation": {
     "quoteId": "QT037fQXs3LGWXea4",
     "receivingCountry": "NG",
     "remittancePurpose": "Gift"
  }
}

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+33472034605"
    } ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    }
  ],
    "transactionStatus": "3000:Remit Success",
    "transactionReference": "TPKM000000056269"  
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"TPKM000000056269", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"businessRule", 
    "errorCode":"3032", 
    "errorDescription":"Remit Failed.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

                                                            

Create a transaction to bank

URL: https://uat-connect.terrapay.com:21211/eig/gsma/transactions

HTTP Request
POST /eig/gsma/transactions HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "descriptionText": "Gift for my brother",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "provider": "2549008",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+27123456789"
    }
    ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    },
     {
      "key": "bankaccountno",
      "value": "2356915085237"
    },
     {
      "key": "sortcode",
      "value": "HDFC0002356"
    },
     {
      "key": "organisationid",
      "value": "HDFCBANK"
    }
  ],
    "senderKyc": {
     "nationality": "FR",
     "dateOfBirth": "28-06-1986",
     "gender": "M",
     "idDocument": [
      {
         "idType": "nationalidcard",
         "idNumber": "123456789",
         "issueDate": "2003-09-26",
         "expiryDate": "2033-09-26",
         "issuerCountry": "FR"
      }
    ],
     "postalAddress": {
       "addressLine1": "49 ",
       "addressLine2": "park street",
       "addressLine3": "walton's road",
       "city": "Lyon",
       "stateProvince": "Lyon",
       "postalCode": "123456",
       "country": "FR"
    },
     "subjectName": {
       "title": "Mr.",
       "firstName": "Einstein ",
       "middleName": "James",
       "lastName": "Bela",
       "fullName": "Einstien James Bela"
    }
  },
    "recipientKyc":
    {
     "subjectName": {
      "firstName": "John",
       "lastName": "Smith",
       "fullName": "John Dave Smith"
    }
    },
   "internationalTransferInformation": {
     "quoteId": "QT037fQXs3LGWXea4",
     "receivingCountry": "NG",
     "remittancePurpose": "Gift"
  }
}

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+33472034605""
    } ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    }
  ],
    "transactionStatus": "3000:Remit Success",
    "transactionReference": "TPKM000000056269"  
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"TPKM000000056269", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"TPKM000000056269", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"businessRule", 
    "errorCode":"3032", 
    "errorDescription":"Remit Failed.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}
                                                            

Create transaction request parameter list:

Parameter name Description Data Type Requirement Field Length
requestDate The creation date and time of the transaction as supplied by the sending partner in YYYY-MM-DD HH:mm:ss format String Mandatory 19
amount Destination amount payable to the beneficiary with precision of 2 decimal places. String Mandatory 10,2
currency Destination amount currency in ISO 4217 format. Eg. NGN String Mandatory 3
type The harmonized Transaction Type. Fixed default value "inttransfer" String Mandatory 11
descriptionText 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. String Optional 0-20
requestingOrganisationTransactionReference Unique Transaction reference generated by the sending partner. String Mandatory 4-50
provider provider value should be same as per the validation request. If different transaction will be rejected.
NOTE: Mandatory for Bangledsh (bank & wallet), Philippines (wallet) termination.
            Optional for other countries.
Numeric Optional 5-12
debitParty:
key msisdn String Mandatory 6
value Sender Mobile Number with country code. Eg. +91xxxxxxxxxx String Mandatory 10-18
creditParty:
Key msisdn String Conditional 6
Value Beneficiary Mobile Number with country code. Eg.+91xxxxxxxxxx. String Optional - For Bank Accounts
Mandatory - For Mobile Wallet
10-18
Key bankaccountno String Conditional 13
Value Beneficiary Bank Account or IBAN Number as applicable in the destination country for receiving funds. Eg. 2365417895.
This key/value pair is optional if the transfer is to a mobile wallet.
String Mandatory - For Bank Accounts
Optional - For Mobile Wallet
5-50
Key sortcode String Conditional 8
Value Bank Code as required in the destination Country. It can be one of
IFSC Code
Routing Code
Swift BIC
This code is specific to bank integration in each country
String Mandatory - For bank accounts
Optional - For mobile wallets
4-25
Key organisationid String Conditional 14
Value Full name of the beneficiary bank String Mandatory - For bank accounts
Optional - For mobile wallets
4-60
senderKyc:
nationality Nationality of the customer in ISO Alpha-2 format. Eg. US String Mandatory 2
dateOfBirth Customer's Date of Birth in YYYY-MM-DD format String Mandatory 10
gender Customer's Gender. Enumeration = (M)ale, (F)emale, (U)nspecified String Optional 1
senderKyc:idDocument:
idType Customer's Id document type:
nationalidcard
drivinglicense
passport
String Mandatory 1-20
idNumber Customer's Id number.
For any other type, it should be Passport Number,Document number. Eg. M123456,123434567
String Mandatory 1-30
issueDate Customer's Id document issue date in YYYY-MM-DD format.
String Mandatory 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format.
String Optional 10
issuerCountry Country where the identification type was issued in ISO Alpha-2 format. String Optional 2
senderKyc:postalAddress:
addressLine1 First line of the address String Mandatory 4-20
addressLine2 Second line of the address String Optional 4-20
addressLine3 Third line of the address String Optional 4-20
city City/Town of sender's address String Mandatory 4-20
stateProvince State of sender's address String Mandatory 4-20
postalCode Postal Code of sender's address String Mandatory 6-8
country Country in ISO Alpha-2 format String Mandatory 2
senderKyc:subjectName:
title Title of the Sender String Optional 0-6
firstName First name of the Sender String Mandatory 1-20
middleName Middle name of the Sender String Optional 0-50
lastName Last name of the Sender String Mandatory 1-20
fullName Full name of the Sender String Mandatory 1-50
recipientKyc:subjectName:
firstName First name of the recipient String Mandatory 1-20
lastName Last name of the recipient String Mandatory 1-20
fullName Full name of the recipient String Mandatory 1-50
internationalTransferInformation:
quoteId The specific quoteId to be used for the transaction. String Mandatory 16-20
receivingCountry Destination Country of international remittance in ISO Alpha 2 format. Eg. NG String Mandatory 2
remittancePurpose Reason for the transfer. Eg Gifts, Family expenses, etc String Mandatory 1-20

Create transaction response parameter list:

Parameter name Description Data Type
requestDate The creation date and time of the transaction as supplied by the client. String
amount Principle Transaction Amount. String
currency Currency of the principal transaction amount. String
type The harmonised Transaction Type String
requestingOrganisationTransactionReference Unique Transaction reference submitted by sending partner as part of request buffer. String
transactionStatus Indicates the status of the transaction String
transactionReference Unique reference for the transaction. This is returned in the response by Terrapay's system String
debitParty:
key msisdn String
value Sender Mobile Number as sent by the partner in the request API String
creditParty:
key msisdn String
value Beneficiary Mobile Number as sent by the partner in the request API String
key bankaccountno String
value Beneficiary bank account details as sent by the partner in the request API String

View A Transaction


GSMA reference https://mmapi.gsma.com/transactions

The View Transactions API is used for viewing the transactions. URI format is:
/transactions/{transactionReference}

View Transaction Status to a Mobile Wallet

URL: https://uat-connect.terrapay.com:21211/eig/gsma/transactions/{transactionReference}

HTTP Request
GET /eig/gsma/transactions/TPKM000000056269 HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+33472034605""
    } ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    }
  ],
    "transactionStatus": "3000:Remit Success",
    "transactionReference": "TPKM000000056269"  
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"TPKM000000056269", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"businessRule", 
    "errorCode":"3032", 
    "errorDescription":"Remit Failed.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

                                                            

View Transaction Status to a Bank Account

URL: https://uat-connect.terrapay.com:21211/eig/gsma/transactions/{transactionReference}

HTTP Request
GET /eig/gsma/transactions/TPKM000000056269 HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+33472034605""
    } ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    }
  ],
    "transactionStatus": "3000:Remit Success",
    "transactionReference": "TPKM000000056269"  
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"authorisation", 
    "errorCode":"1003", 
    "errorDescription":"Authentication failed. Username or Password is incorrect.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
{
  "serverCorrelationId":"TPKM000000056269", 
  "clientCorrelationId":"partnerRefId1234",
  "error": {
    "errorCategory":"businessRule", 
    "errorCode":"3032", 
    "errorDescription":"Remit Failed.", 
    "errorDateTime":"2017-05-02 11:00:00"
  }
}

                                                            

View transaction request parameter list:

Parameter name Description Data Type Requirement
transactionReference Unique reference for the transaction which was returned by transaction response buffer by Terrapay's system. String Mandatory

View transaction response parameter list:

Parameter name Description Data Type
requestDate The creation date and time of the transaction as supplied by the client. String
amount Principle Transaction Amount. String
currency Currency of the principal transaction amount. String
type The harmonised Transaction Type String
requestingOrganisationTransactionReference Unique Transaction reference generated by the sending partner. String
transactionStatus Indicates the status of the transaction String
transactionReference Unique reference for the transaction. This is returned in the response by Terrapay's system String
debitParty:
key The name of the debitparty account identifier String
value Keys include MSISDN and Wallet Identifier String
creditParty:
key The name of the creditparty account identifier String
value Keys include MSISDN and Wallet Identifier String

Ledger Balance


GSMA reference https://mmapi.gsma.com/accounts/

The balance API is used for checking the current balance in the partner's ledger in either a particular currency or all currency ledgers currently active for the partner URI format is:
accounts/{currency}/balance

Get Balance of all ledgers.

URL: https://uat-connect.terrapay.com:21211/eig/gsma/accounts/all/balance

HTTP Request
GET /eig/gsma/accounts/all/balance HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
[
    {
        "currency": "USD",
        "currentBalance": "1000.000000",
        "status": "available"
    },
    {
        "currency": "NGN",
        "currentBalance": "3000000.000000",
        "status": "available"
    },
    {
        "currency": "TZS",
        "currentBalance": "1000000.000000",
        "status": "available"
    }
]

                                                            

Get Balance for a single currency ledger.

URL: https://uat-connect.terrapay.com:21211/eig/gsma/accounts/USD/balance

HTTP Request
GET /eig/gsma/accounts/USD/balance HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
[
    {
        "currency": "USD",
        "currentBalance": "1000.000000",
        "status": "available"
    }
]

                                                            

Corridor Quotes


GSMA reference https://mmapi.gsma.com/accounts/

This API is used to get the FxRates for all the corridors that are currently configured. URI format is:
/quotations/all

URL: https://uat-connect.terrapay.com:21211/eig/gsma/quotations/all

HTTP Request
GET /eig/gsma/quotations/all HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "terrapayuser"
X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"US"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2017-05-03 11:00:00"
[
    {
		"requestDate": "2017-10-18 09:27:16",
		"requestCurrency": "USD",
		"quotes":[
		{
		"receivingServiceProvider": "GH",
		"receivingCurrency": "GHS",
		"fxRate": "4.966000"
		},
		{
		"receivingServiceProvider": "UG",
		"receivingCurrency": "UGX",
		"fxRate": "3728.000597"
		}
		],
        "quotationStatus": "9000:Success"
    }
]
 
   
                                                            

Response Codes & Messages



Response Code Response Message Contact TerraPay Transaction Action Remarks/Comments
1000 Invalid [propertyName] No Retry Check for invalid request parameter(s)
1001 [propertyName] value should be between [minlength] to [maxlength] No Retry Check for invalid request parameter(s)
1002 [propertyName] must be [length] No Retry Check for invalid request parameter(s)
1003 Authentication failed. Username or Password is incorrect. Yes Retry Contact TerraPay operations team for valid username and password.
1004 Invalid parameters in the request No Retry Check for invalid request parameter(s).
1005 Mandatory fields are missing No Retry Check for invalid request parameter(s).
1006 Request SHA256 checksum mismatch No Retry Check for invalid checksum sent with request.
1007 Server is busy.Please try after sometime Yes Retry Failure due to network issues or unhandled exceptions.
1010 Source country not allowed Yes Retry Operation team needs to check source country configuration.
1011 Destination country not allowed Yes Retry Operation team needs to check destination country configuration.
1012 Source currency not allowed Yes Retry Operation team needs to check source currency configuration.
1013 Destination currency not allowed Yes Retry Operation team needs to check destination currency configuration.
1014 Source country inactive Yes Retry Operation team needs to check source country configuration.
1015 Destination country inactive Yes Retry Operation team needs to check destination country configuration.
1016 Failed to get destination partner Yes Retry Operation team needs to check corridor configuration.
1017 Source partner validity fail Yes Retry operations team needs to extend validity of source partner in system.
1018 Destination partner validity fail Yes Retry operations team needs to extend validity of destination partner in system.
1019 Source partner suspended Yes Retry operations team needs to check activation status of partner.
1020 Destination partner suspended Yes Retry operations team needs to check activation status of partner.
1021 Source partner inactive Yes Retry operations team needs to check activation status of partner.
1022 Destination partner inactive Yes Retry operations team needs to check activation status of partner.
1023 Corridor validity failed Yes Retry operations team needs to check corridor validity.
1024 Corridor Suspended Yes Retry operations team needs to check corridor activation status.
1026 Source MSISDN not allowed. No Cancel Invalid source/sender's mobile number.
1027 Source MSISDN Blacklisted. No Cancel Source/sender's mobile number is black listed.
1028 Destination MSISDN not allowed. No Cancel Invalid destination mobile number.
1029 Destination MSISDN Blacklisted. No Cancel Destination mobile number is black listed.
1030 Corridor not exists Yes Retry Operation team needs to check corridor configuration.
1031 Source currency inactive Yes Retry Operation team needs to check currency configuration.
1032 Destination currency inactive Yes Retry Operation team needs to check currency configuration.
1046 Invalid Transaction ID. No Retry Check for transaction Id format (special characters).
Response Code Response Message Contact TerraPay Transaction Action Remarks/Comments
2000 Quote Success No No Quotation is success.
2001 Source amount is invalid No Retry Send correct/valid source amount with quote request.
2002 Beneficiary MSISDN validation failed No Cancel Beneficiary validation is in failure state for which quote request is initiated.
2003 Failed to get Forex rate Yes Retry Operation team needs to check rate configuration.
Response Code Response Message Contact TerraPay Transaction Action Remarks/Comments
3000 Remit Success No No Transaction is in success state.
3050 Remit Acknowledged, status PENDING No Poll Partner needs to poll status API till transaction status changes to success/failed.
3001 Transaction request should be current date.. No Retry Transaction request should be current date.
3002 Beneficiary Validation failed No Cancel Beneficiary validation is in failure state for which remit request is initiated.
3003 TerraPay transaction id is invalid No Retry Retry transaction with valid TerraPay transaction id.
3004 Duplicate transaction Id No Cancel Send transaction with unique transaction/reference id.
3005 Quote and Remit parameters do not match No Retry Send the parameters as per API specification.
3006 Sender KYC validation failed No Cancel Transaction is failed.
3007 Beneficiary KYC validation failed No Cancel Transaction is failed.
3008 Quote expired No Cancel Initiate a new a quote request and send new quote reference with remit request.
3009 Failed to process quote request Yes Retry Operation team needs to check.
3010 Mandatory KYC parameter check failed No Retry Check for sender's KYC parameters in remit request.
3022 Corridor validation failed Yes Retry Operation team needs to check the corr configuration.
3030 Possible duplicate transaction received within configured time. Yes Retry Wait for sometime and send the transaction again.
3031 Connection timeout while connecting to destination partner Yes Retry Wait for sometime and send the transaction again.
3032 Remit failed Yes Cancel Operation team needs to check logs and update.
3072 Receiver Daily Transaction Limit Reached No Cancel Beneficiary daily transaction limit has reached.
3075 Sending Partner Min allowed amount check failed. No Cancel Sending partner is sending less than minimum confiured transaction amount.
3076 Sending Partner Max allowed amount check failed. No Cancel Sending partner is sending more than maximum configured transaction amount.
3077 Receiving Partner Min allowed amount check failed. No Cancel Receiving partner is receiving less than minimum confiured transaction amount.
3078 Receiving Partner Max allowed amount check failed. No Cancel Receiving partner is receiving more than maximum confiured transaction amount.
3079 Sender Min allowed amount check failed. No Cancel Sender is sending less than minimum confiured transaction amount.
3080 Sender Max allowed amount check failed. No Cancel Sender is sending more than maximum confiured transaction amount.
3081 Receiver Min allowed amount check failed. No Cancel Beneficiary is receiving less than minimum confiured transaction amount.
3082 Receiver Max allowed amount check failed. No Cancel Beneficiary is receiving more than maximum confiured transaction amount.
3100 Credit Failed. Msisdn not found. No Cancel Transaction has failed due to invalid wallet account.
3101 Bank Credit Failed. Invalid Account. No Cancel Transaction has failed by bank due to invalid bank account.
3102 Bank Credit Failed. Bank Not Reachable. No Cancel Transaction failed by destination partner as bank is not reachable.
3103 Bank credit failed. Account name mismatch. No Cancel Transaction failed by bank due to account name mismatch.
3104 Bank credit failed. Transaction limit exceeded. No Cancel Transaction failed by bank as transaction limit exceeded.
3105 Bank credit failed. Transaction not permitted. No Cancel Transaction failed by bank as transaction is permitted.
3106 Bank credit failed. Unknown Error. Yes Retry/Cancel As the transaction failed by bank, please check with operations team either transaction can be retried or not.
3107 Invalid Amount Limit. No Cancel Transaction failed due to max limit per transaction.
3108 Invalid Digital Signature. Yes Cancel Transaction has failed due to account not registed.
3109 Insufficient funds in the receiving partner account. Yes Cancel Operation team needs to check the prefunding balance.
3110 Invalid Beneficiary Account Yes Cancel Transaction has failed due to invalid account.
3111 Beneficiary Account not Registered Yes Cancel Transaction has failed due to account not registed.
3112 Duplicate VendorId No Cancel Send the correct vendorID.
3113 Beneficiary Account Limit Reached. No Cancel Transaction failed due to transaction limit exceeded.
3114 Beneficiary Account Barred. No Cancel Transaction failed as account is Barred.
3115 Beneficiary Account Inactive No Cancel Transaction failed as account is inactive.
3116 Beneficiary Account Locked No Cancel Transaction failed as account is locked.
3132 Remit Failed - Max retry limit reached. No Cancel Transaction failed as transaction limit exceeded.
Response Code Response Message
5000 Credit Success
5001 Credit Acknowledged, status PENDING
5002 Duplicate transaction
5003 Beneficiary Authentication expired
5004 Beneficiary MSISDN validation failed
5005 Dst Amount invalid
5006 Dst Currency invalid
5007 Beneficiary MSISDN wallet does not exist
5008 Credit amount requested is invalid
5009 Credit amount requested is too small.
5010 Credit amount requested is too large
5011 Credit amount requested is not in valid range
5012 Credit Agent endpoint has non-zero balance
5013 Credit Message was too long
5014 Wallet has insufficient funds
5015 Wallet Balance exceeded
5016 Wallet Cap exceeded
Response Code Response Message Contact TerraPay Transaction Action Remarks/Comments
6000 Beneficiary MSISDN Validation Success No No Transaction validation is success.
6001 Corridor does not exists Yes Retry Operation team needs to check the corridor configuration.
6002 Corridor inactive Yes Retry Operation team needs to check the corridor configuration.
6003 Beneficiary MSISDN blacklisted No Cancel Beneficiary MSISDN has been blacklisted on TerraPay system..
6004 Beneficiary validation failed Yes Cancel Operation team needs to check.
6005 Beneficiary Registered but not KYCed No Cancel Beneficiary is registered with destination partner network with incomplete KYC details.
6006 Beneficiary MSISDN not found No Cancel Beneficiary is not registered with destination partner network.
6007 Beneficiary Suspended No Cancel Beneficiary is in suspended state on TerraPay system.
6008 Beneficiary name does not match No Cancel Beneficiary validation failed.
6009 Beneficiary validation failed. Request timed out at destination partner Yes Retry Operation team needs to check the time out issue.
6010 Mandatory KYC parameter check failed Yes Retry Resend the transaction with required KYC parameters.
6011 Validation Failed. Beneficiary must register or upgrade KYC Level to receive transactions No Cancel Beneficiary validation failed.
6012 Beneficiary KYC Verification Pending No Cancel Beneficiary validation failed.
6013 Receiver Name Missing No Cancel Beneficiary validation failed.
6014 Customer Not Registered No Cancel Beneficiary validation failed.
6017 Beneficiary Account is locked No Cancel Beneficiary validation failed.
6019 Destination Partner Timed Out - Please retry. Yes Retry Operation team needs to check time out issue.
6022 Beneficiary Account Inactive No Cancel Beneficiary validation failed.
6020 Beneficiary Account is Inactive No Cancel Beneficiary validation failed.
6101 Destination bank not configured Yes Retry Operation team needs to check configuration.
6102 Invalid Bank Account Number No Cancel Send the transaction with valid account number.
6103 Destination bank not reachable Yes Retry Operation team needs to check.
6104 Validation Failed at Destination Partner Yes Retry Operation team needs to check.
6023 Provider code is missing No Cancel Send the transaction with valid provider code.
6024 Provider code does not match operator network No Cancel Send the transaction with valid provider code.


About Us

TerraPay is a Global transaction processing, clearing and settlement service for mobile wallets. We provide the interoperability engine that enables customers to send and receive realtime transactions across diverse payment instruments, platforms and regions.

We believe in the power of the mobile and are building the digital payment rails to fulfill our vision of being able to send money to any mobile.

TerraPay is a B2B company incubated by Comviva, a global leader in delivering mobile financial solutions and is part of the USD 18 billion Mahindra Group. TerraPay is registered and regulated in several jurisdictions. In UK, it is regulated by the Financial Conduct Authority (FCA).

For more information on TerraPay visit www.terrapay.com

TerraPay is platform agnostic and supports standard open APIs for integration with any mobile wallet provider. Through a single connection, partners gain access to a global payment network enabling rapid services up-scaling whilst minimizing Opex and Capex investments. As a fully regulated financial intermediary services network, TerraPay offers services beyond principal core transaction, routing and processing functions and assumes end-to-end responsibility for, regulatory compliance foreign exchange management and funds settlement.

Terrapay Services (UK) Limited is registered and regulated by the Financial Conduct Authority (FCA) and HM Revenue and Customs in the UK.

TerraPay is an offering by Comviva - a global leader in mobility solutions.

Click here for more information on Comviva.