Introduction


Purpose


The purpose of this document is to describe the various interfaces available on the TerraPay network for international money remittances and the associated services and transaction flows.


Scope


The scope of this document is to give a detailed explanation on the APIs that are hosted on the TerraPay network and how partners can use these APIs to integrate into TerraPay to send transactions.


Audience


This document is to be used by

  • TerraPay technical team
  • Partner technical team


Acronyms and Abbreviations


IMT International Money Transfer
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 Second
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. The send partner system will provide and manage the necessary interfaces required by the sender to create an international money transfer request.
  2. The send partner system then integrates with TerraPay to access the services provided.
  3. TerraPay will integrate directly with receiving partner systems to delivery funds to the beneficiary.
  4. The sender is a registered subscriber on the sending partner system.
  5. The beneficiary is a registered subscriber on the receiving partner system.
  6. A partner should be able to authenticate a subscriber with valid KYC documents.
  7. Connectivity between the partner network and TerraPay network can be over S2S VPN or by white listing of IPs
  8. The S2S VPN tunnel provides a secure and encrypted connection between the partner's system and TerraPay's system.
  9. The partner system will use HTTPS/JSON based API integration with the TerraPay system.
  10. TerraPay will provide a secure SSL certificate to use for APIs connecting into the partner system.
  11. The partner will provide a secure SSL certificate to use for APIs connecting into the TerraPay system.
  12. In order to provide good end user experiences the response times to API requests should be as low as possible
  13. All timestamps on the TerraPay system are in GMT.


Connectivity, Staging & Production


TerraPay system's are hosted on AWS across regions where available. A partner connecting to TerraPay system will connect to the nearest AWS region which is in close proximity to the partner network. TerraPay systems are hosted as primary (Live) site, DR site and GR site. TerraPay will connect to partner DR and GR systems as well to ensure service is not impacted when primary sites are down.

Partner systems are allowed access to the TerraPay network through a secure VPN tunnel. This is set up in both the primary and DR setups. Each of these will have two VPN tunnels, active and standby.

All the API interfaces between TerraPay and partner will be on HTTPS. TerraPay's inbound APIs are protected with a CA issued SSL certificate. Partner must also secure a CA issued SSL certificate for all APIs.

Partners integrate with TerraPay, on the EIG (External Interface Gateway) system which are hosted in a DMZ (De-Militarized Zone) of the TerraPay network. Access to all inbound and outbound APIs will be provided on the TerraPay staging system for integration testing. After API testing and validations are done then partners will be migrated to live production systems.


Services


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

  1. Remit to Mobile
  2. Remit to Bank


Remit to Mobile


This service enables the sender to instantly send money to a beneficiary's mobile number. The money is credited through a payment instrument associated with the beneficiary's mobile number. This could be a mobile network operator wallet, a mobile money operator wallet, a bank wallet or a bank account which is mapped to the mobile number. TerraPay automatically routes the transaction through the available payment instrument.

A sender can initiate the money transfer from a mobile wallet, bank account or cash over the counter. This depends on the interfaces provided by the sending partner.

remit to mobile


Remit to Bank


This service enables the sender to send money to a beneficiary's bank account.
The sender can initiate the money transfer from a wallet, bank account or cash over the counter. This depends on the interfaces provided by the sending partner.


remit to bank



TerraPay APIs


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

Basic Transaction Steps
  • Sender initiates a transaction from,
    • A registered Mobile Wallet
    • An active Bank Account
    • At a MTO agent
  • 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 associated 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.
  • In addition where ever the receiving partner can provide the beneficiary name, TerraPay does name matching using a propriety fuzzy logic algorithm
  • Sender then initiates a quote request. Sender provides the amount to be transferred. TerraPay will process the quote and provide the sender with the foreign exchange rate and the amount the beneficiary will receive.
  • Sender then confirms the transaction.
  • TerraPay 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 sanctions screening and AML/CFT validations. This information is mandatory and has to be 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 the on boarding process on test and production environments separately.
Username and Password is always case-insensitive.
X-PASSWORD must be SHA256 hash encoded when sent over the API request.

Inbound APIs


The Inbound APIs will be used by sending partners to integrate with TerraPay to send transaction requests.

View Account Status




The Accounts Status API validates the status of the beneficiary wallet or bank account and also matches the name of the beneficiary provided by the sender with the name of the beneficiary registered on the financial instrument. This service is available only in corridors where the receiving partner provides details of the beneficiary account such as the account state and beneficiary name. In cases where this information is not available TerraPay does basic validation on the mobile number and bank account format. The status enables the client to determine whether transactions can be subsequently sent to the beneficiary account. URI format is: https://uat-connect.terrapay.com:21211/eig/gsma/accounts/{AccountIdentifiers}/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 which indicates the mobile operator network to which the transaction is to be sent.
This field is conditional. If not set, TerraPay will automatically find the mobile network that the beneficiary MSISDN belongs to and will validate the MSISDN.
If set, then TerraPay will validate the MSISDN against the mobile network specified. In case the provider code does not match the mobile network the validation will be rejected.
NOTE:
● Mandatory for wallet transactions to China, Bangladesh, Indonesia, Nepal, Pakistan, Philippines, South Sudan, Togo, Vietnam, Cambodia, Columbia & Haiti.
● 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}&banksubcode={banksubcode}

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 Parameters

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 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 the 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 bank transactions to Bangladesh & China.
● Mandatory provider code for China Union Pay is CNUNIONPAY.
● Mandatory provider code for Philippines Direct to bank transfer is PH_DIRECT_TO_BANK.
● Optional for other countries.
Numeric Conditional 7-12
banksubcode This is a code that indicates the branch code of the specific bank to which the transaction is to be sent.
NOTE:
● Mandatory for bank transactions to Brazil & Uruguay.
● If the transaction is to Bangladesh then partner can send rounting number in banksubcode and they do not have to send the provider code.
● Optional for other countries.
String Conditional 5

Response Parameters

Parameter name Description Data Type Validation
status Indicates the status of the account. If 'available' then the account can receive funds. If not then transactions sent to the account will fail. 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 organization holding the account. String Length = 20, Regular Expression

Create Quotation



The quotations API is used to obtain the foreign exchange rate between a currency pair. 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 "Recieve Bank Account 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: The quotation object which has the foreign exchange rate and the source and destination amounts. The quotation reference should be used in the transactions as an acceptance of the exchange rate.
quoteId The unique ID for this quote provided by the foreign exchange provider.This id will be used by partner as part of transaction request. String
quoteExpiryTime The time stamp after which the quote will not be valid. 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




The Transactions API is used to initiate an international money remittance transaction. 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":{
		"nationality": "FR",
		"dateOfBirth": "1986-06-28",
		"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"
		}
	},
	"internationalTransferInformation": {
		"quoteId": "QT037fQXs3LGWXea4",
		"receivingCountry": "NG",
		"remittancePurpose": "Gift",
		"sourceOfFunds": "Salary",
		"relationshipSender": "Brother"
	}
}

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": null,
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "4119314191318",
   "debitParty": [
		{
			"key": "msisdn",
			"value": "+27123456789"
		}
	],
	"creditParty": [
		{
			"key": "bankaccountno",
			"value": "718530346"
		},
		{
			"key": "sortcode",
			"value": "0001"
		},
		{
			"key": "organisationid",
			"value": "Nu Pagamentos"
		},
		{
			"key": "banksubcode",
			"value": "0001"
		},
		{
			"key": "msisdn",
			"value": "+33472034605"
		}
	],
	"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": {
		"nationality": "FR",
		"dateOfBirth": "28-06-1986",
		"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": {
			"firstName": "John",
			"lastName": "Smith",
			"fullName": "John Dave Smith"
		}
	},
	"internationalTransferInformation": {
		"quoteId": "QT037fQXs3LGWXea4",
		"receivingCountry": "NG",
		"remittancePurpose": "Gift",
		"sourceOfFunds": "Salary",
		"relationshipSender": "Brother"
	}
}

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 sent in the validation request. If a different value is sent then the transaction will be rejected.
NOTE:
● Mandatory for transactions to Bangladesh (bank & wallet), China (bank & wallet), Nepal (wallet), Pakistan (wallet), Philippines (wallet), South Sudan (wallet), Indonesia (wallet).
● 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
Key banksubcode String Conditional 1-10
Value This is a code that indicates the branch code of the specific bank to which the transaction is to be sent.
NOTE:
● Mandatory for bank transactions to Brazil & Uruguay.
● Optional for other countries.
● If the transaction is to Bangladesh then partner can send rounting number in banksubcode and they do not have to send the provider code.
String Mandatory - For bank accounts
Optional - For mobile wallets
1-10
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 Optional 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format.
String Mandatory 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 Optional 4-20
postalCode Postal Code of sender's address String Optional 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:
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
recipientKyc: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 Optional 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format.
String Mandatory 10
issuerCountry Country where the identification type was issued in ISO Alpha-2 format. String Optional 2
recipientKyc: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 Optional 4-20
postalCode Postal Code of sender's address String Optional 6-8
country Country in ISO Alpha-2 format String Mandatory 2
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.

    Click here to find the accepted values.

String Mandatory 4-30
sourceOfFunds Source of funds.

    Click here to find the accepted values.

String Mandatory 4-17
relationshipSender The relation between the sender and the beneficiary.

    Click here to find the accepted values.

String Mandatory 3-11

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



The View Transactions API is used for looking up the status of a transaction already sent to the TerraPay system. 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 in the response of the createTransaction API or the unique reference generated by the partner's system and sent in the createTranactin API request. 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



The ledger balance API is used for get the current balance in the partner's ledger. The balance can be retrieved for a particular currency ledger or all currencies ledger. The ledger balance is retrieved only if the ledger is active. 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



This API is used to get the foreign exchange rates for all the corridors that are active for the partner.
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"
    }
]
 
   
                                                            

Cancel Transaction



This API is used to cancel an initiated transaction which is not yet credited. The cancellation will be done only if the transaction is pending on the TerraPay system and has not already been sent to the receiving partner for credit to the beneficiary account.

      URL: https://uat-connect.terrapay.com:21211/eig/gsma/remitCancel/
      
      HTTP Request
      
      POST /eig/gsma/remitCancel HTTP/1.1
      Host: xxx.xxx.xxx.xxx
      Content-Type: text/json; charset=utf-8
      X-USERNAME: "terrapayuser"
      X-PASSWORD: "101dfd2422f23f06120b77ab17d39229ff9bb40563eae042bc6cc6e8f9f1825b"
      X-DATE: "2021-01-03 11:00:00"
      X-ORIGINCOUNTRY:"US"
      
      {
        "cancelreason": "cancelling",
        "txnId": "TPSE000000298941"
      }
	  
	  
      HTTP Response - Success
      HTTP/1.1 201 OK
      Content-Type: text/json; charset=utf-8
      X-DATE: "2021-01-03 11:00:00"
      
      {
        "responseMessage": "Cancel Success",
        "statusCode": "15000"
      }
      

Cancel transaction request parameter list:

Parameter name Description Data Type Requirement
txnId Reference for the transaction which was returned by transaction response buffer by Terrapay's system or partner transaction id. String Mandatory

Response code for cancel transactions:


Response Code Response Message
15000 Cancel Success.
15001 Cannot Cancel. Credit already in process.
15002 Cannot Cancel. Transaction in Success state.
15003 Cannot Cancel. Transaction in Fail state.
15004 Cannot Cancel. Transaction not found.
15005 Transaction already in canceled state.

Reverse Transaction



Reverse Transaction is used to reverse a transfer which is to bring back the money from the beneficiary's account to the sender's account.

Note: Reversal of transaction is only possible for transaction response code:3000, Transaction Successful.

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

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

{
  "reversalReason": "reversalreason",
  "txnId": "TPKM000000056269"
}


HTTP Response - Success
HTTP/1.1 201 OK
Content-Type: text/json; charset=utf-8
X-DATE: "2021-01-03 11:00:00"

{
  "responseMessage": "Reverse Success",
  "statusCode": "16000"
}
                      

Reverse transaction response parameter list:

Parameter name Description Data Type Requirement
txnId Reference for the transaction which was returned by transaction response buffer by Terrapay's system or partner transaction id. String Mandatory

Response code for reversal transactions:


Response Code Response Message
16000 Reversal Success.
16001 Reversal Failed. Transaction Not found.
16002 Reversal Rejected.
16003 Reversal Pending.
16004 Reversal cannot be done at this stage.
16005 Reversal already raised.
16006 Transaction already reversed.
16007 Reverse cannot be done. Transaction is in failed state.

Statements API


Statement Types

TRANSFERRED

Represents successfully transferred transaction. Balance should be deleted

REJECTED

Represents transactions rejected by TerraPay. Balance shouldn't be changed. The reason of the rejection should be populated.

BOUNCED

Represents bounced-back transactions. Balance should be credited. Happens when a beneficiary bank returns funds back to TerraPay due to incorrect details, etc.

LIQUIDITY

Represents liquidity transactions sent to TerraPay. Balance should be credited.

Statement fields
Name Format Example Requirement Description
timestamp ISO 8601 UTC DateTime 2020-04-29T13:00:00Z Mandatory Transaction time
type TRANSFERRED REJECTED BOUNCED LIQUIDITY Mandatory Transaction time
internalRef String TPKM000000056269 Mandatory TerraPay transaction reference
externalRef String 88440865645 Optional for LIQUIDITY mandatory for the rest Partner transaction reference
amount Decimal 123.45 Mandatory Transaction amount in balance currency
currency ISO 4217 three-letter code USD Mandatory Balance currency, USD
convertedAmount Decimal 4497.45 Optional for LIQUIDITY mandatory for the rest Converted amount sent to beneficiary
convertedCurrency ISO 4217 three-letter code TZS Optional for LIQUIDITY mandatory for the rest Currency of convertedAmount
balance Decimal 212455.87 Mandatory Balance value after the transaction
message String 3032:Remit Failed. Mandatory Extra transaction description should contain parseable reason for REJECTED and BOUNCED type

Statement's example
Description Timestamp Type InternalRef ExternalRef Amount Currency Converted Amount Converted Currency Balance Message
Partner sends funds to TerraPay 2020-04-29T13:00:00Z LIQUIDITY TP000000000 1000.00 USD 1000.00 Transfer with reference 123456
Successful transfer for 38280.09 UGX 2020-05-22T09:12:42Z TRANSFERRED TP000000001 TW000000000 10.12 USD 38280.09 UGX 989.88 3000:Remit Success
Failed transfer for 19938.06 TZS 2020-05-22T10:15:55Z REJECTED TP000000002 TW000000001 8.62 USD 19938.06 TZS 989.88 Transfer with reference 123456
Previously successful transfer to UGX was returned to TerraPay 2020-05-22T11:22:45Z BOUNCED TP000000003 TW000000000 10.12 USD 38280.09 UGX 1000.00 3103:Bank credit failed. Account name mismatch

Request

Statements should be accessible via HTTP GET request.

Sample URL

URL: https://uat-connect.terrapay.com:21211/eig/gsma/statements?start=%7Bstart%7D&end=%7Bend%7D¤cy=%7Bcurrency%7D

Request parameter
Name Format Example Requirement Description
start ISO 8601 UTC DateTime 2020-04-29T13:00:00Z mandatory Beginning of the query interval
end ISO 8601 UTC DateTime 2020-05-22T19:38:59Z mandatory End of the query interval

Request headers

Request must include standard TerraPay headers:

  • X-USERNAME
  • X-PASSWORD
  • X-DATE
  • X-ORIGINCOUNTRY

Response

Response should contain list of statements in JSON format for the requested period.

Example

[
	{
"timestamp": "2020-04-29T13:00:00Z", "type": "LIQUIDITY", "internalRef": "TP000000000", "externalRef": "", "amount": "1000.00", "currency": "USD", "convertedAmount": "", "convertedCurrency": "", "balance": "1000.00", "message": "Transfer with reference 123456" }, { "timestamp": "2020-05-22T09:12:42Z", "type": "TRANSFERRED", "internalRef": "TP000000001", "externalRef": "TW000000000", "amount": "10.12", "currency": "USD", "convertedAmount": "38280.09", "convertedCurrency": "UGX", "balance": "989.88", "message": "3000:Remit Success" }, { "timestamp": "2020-05-22T10:15:55Z", "type": "REJECTED", "internalRef": "TP000000002", "externalRef": "TW000000001", "amount": "8.62", "currency": "USD", "convertedAmount": "19938.06", "convertedCurrency": "TZS", "balance": "989.88", "message": "3007:Beneficiary KYC validation failed" }, { "timestamp": "2020-05-22T11:22:45Z", "type": "BOUNCED", "internalRef": "TP000000003", "externalRef": "TW000000000", "amount": "10.12", "currency": "USD", "convertedAmount": "38280.09", "convertedCurrency": "UGX", "balance": "1000.00", "message": "3103:Bank credit failed. Account name mismatch" } ]

Get Bank List




The Bank list API is used to derive a bank name, code, provider code, and status. URI format is: https://connect.terrapay.com:21211/eig/getbanklist/{countrycode}

Note: This example is exclusive to Bangladesh.


Get Bank List.

URL: https://connect.terrapay.com:21211/eig/getbanklist/BD
				
HTTP Request
GET /eig/getbanklist/BD HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
X-USERNAME: "username"
X-PASSWORD: "password"
X-DATE: "request datetime"
X-ORIGINCOUNTRY:"origincountry"

				
response-HTTP 200
				
{
	"countryCode": "BD",
	"lastUpdatedOn": "2021-01-12 21:40:00.051",
	"banks": [
	{
		"bankName": "DUTCH BANGLA BANK LIMITED",
		"bankCode": "DBBLBDDH",
		"providerCode": "88090010000",
		"status": "ACTIVE"
	},
	{
		"bankName": "AGRANI BANK LTD",
		"bankCode": "AGBKBDDH",
		"providerCode": "88090030000",
		"status": "ACTIVE"
	},
	{
		"bankName": "AB BANK LTD",
		"bankCode": "ABBLBDDH",
		"providerCode": "88090020000",
		"status": "ACTIVE"
	},
	{
		"bankName": "AL-ARAFAH ISLAMI BANK LTD",
		"bankCode": "ALARBDDH",
		"providerCode": "88090040000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BANGLADESH COMMERCE BANK LTD",
		"bankCode": "BCBLBDDH",
		"providerCode": "88090060000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BANGLADESH DEVELOPMENT BANK LTD",
		"bankCode": "BDDBBDDH",
		"providerCode": "88090070000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BANGLADESH KRISHI BANK",
		"bankCode": "BKBABDDH",
		"providerCode": "88090080000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BANGLADESH SAMABAYA BANK LTD",
		"bankCode": "BSBABDDH",
		"providerCode": "88090040000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BANK AL-FALAH LTD",
		"bankCode": "ALFHBDDH",
		"providerCode": "88090100000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BANK ASIA LTD",
		"bankCode": "BALBBDDH",
		"providerCode": "88090110000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BASIC BANK LTD",
		"bankCode": "BKSIBDDH",
		"providerCode": "88090120000",
		"status": "ACTIVE"
	},
	{
		"bankName": "BRAC BANK LTD",
		"bankCode": "BRAKBDDH",
		"providerCode": "88090130000",
		"status": "ACTIVE"
	},
	{
		"bankName": "CITI BANK N A",
		"bankCode": "CITIBDDX",
		"providerCode": "88090140000",
		"status": "ACTIVE"
	},
	{
		"bankName": "COMMERCIAL BANK OF CYLON",
		"bankCode": "CCEYBDDH",
		"providerCode": "88090150000",
		"status": "ACTIVE"
	},
	{
		"bankName": "DHAKA BANK LTD",
		"bankCode": "DHBLBDDH",
		"providerCode": "88090160000",
		"status": "ACTIVE"
	},
	{
		"bankName": "EASTERN BANK LTD",
		"bankCode": "EBLDBDDH",
		"providerCode": "88090170000",
		"status": "ACTIVE"
	},
	{
		"bankName": "FIRST SECURITY ISLAMI BANK LTD",
		"bankCode": "FSEBBDDH",
		"providerCode": "88090190000",
		"status": "ACTIVE"
	},
	{
		"bankName": "HABIB BANK LTD",
		"bankCode": "HABBBDDH",
		"providerCode": "88090200000",
		"status": "ACTIVE"
	},
	{
		"bankName": "HONGKONG and SHANGHAI BANKING CORP",
		"bankCode": "HSBCBDDH",
		"providerCode": "88090210000",
		"status": "ACTIVE"
	},
	{
		"bankName": "ICB ISLAMIC BANK LTD",
		"bankCode": "BBSHBDDH",
		"providerCode": "88090220000",
		"status": "ACTIVE"
	},
	{
		"bankName": "IFIC BANK LTD",
		"bankCode": "IFICBDDH",
		"providerCode": "88090230000",
		"status": "ACTIVE"
	},
	{
		"bankName": "ISLAMI BANK BANGLDESH LTD",
		"bankCode": "IBBLBDDH",
		"providerCode": "88090240000",
		"status": "ACTIVE"
	},
	{
		"bankName": "JAMUNA BANK LTD",
		"bankCode": "JAMUBDDH",
		"providerCode": "88090250000",
		"status": "ACTIVE"
	},
	{
		"bankName": "MEGHNA BANK LIMITED",
		"bankCode": "MGBLBDDH",
		"providerCode": "88090270000",
		"status": "ACTIVE"
	},
	{
		"bankName": "MERCANTILE BANK LTD",
		"bankCode": "MBLBBDDH",
		"providerCode": "88090280000",
		"status": "ACTIVE"
	},
	{
		"bankName": "MIDLAND BANK LIMITED",
		"bankCode": "MDBLBDDH",
		"providerCode": "88090290000",
		"status": "ACTIVE"
	},
	{
		"bankName": "MODHUMOTI BANK LIMITED",
		"bankCode": "MODHBDDH",
		"providerCode": "88090300000",
		"status": "ACTIVE"
	},
	{
		"bankName": "MUTUAL TRUST BANK LTD",
		"bankCode": "MTBLBDDH",
		"providerCode": "88090310000",
		"status": "ACTIVE"
	},
	{
		"bankName": "NATIONAL BANK LTD",
		"bankCode": "NBLBBDDH",
		"providerCode": "88090320000",
		"status": "ACTIVE"
	},
	{
		"bankName": "NATIONAL BANK OF PAKISTAN",
		"bankCode": "NBPABDDH",
		"providerCode": "88090330000",
		"status": "ACTIVE"
	},
	{
		"bankName": "NATIONAL CREDIT COMMERCE BANK LTD",
		"bankCode": "NCCLBDDH",
		"providerCode": "88090340000",
		"status": "ACTIVE"
	},
	{
		"bankName": "NRB BANK LIMITED",
		"bankCode": "NRBDBDDH",
		"providerCode": "88090350000",
		"status": "ACTIVE"
	},
	{
		"bankName": "NRB COMMERCIAL BANK LTD",
		"bankCode": "NRBBBDDH",
		"providerCode": "88090360000",
		"status": "ACTIVE"
	},
	{
		"bankName": "NRB GLOBAL BANK LIMITED",
		"bankCode": "NGBLBDDH",
		"providerCode": "88090370000",
		"status": "ACTIVE"
	},
	{
		"bankName": "ONE BANK LTD",
		"bankCode": "ONEBBDDH",
		"providerCode": "88090380000",
		"status": "ACTIVE"
	},
	{
		"bankName": "PRIME BANK LTD",
		"bankCode": "PRBLBDDH",
		"providerCode": "88090390000",
		"status": "ACTIVE"
	},
	{
		"bankName": "PUBALI BANK LTD",
		"bankCode": "PUBABDDH",
		"providerCode": "88090400000",
		"status": "ACTIVE"
	},
	{
		"bankName": "RAJSHAHI KRISHI UNNAYAN BANK",
		"bankCode": "RKUBBDDH",
		"providerCode": "88090410000",
		"status": "ACTIVE"
	},
	{
		"bankName": "RUPALI BANK LTD",
		"bankCode": "ALARUPBBDDHRBDDH",
		"providerCode": "88090420000",
		"status": "ACTIVE"
	},
	{
		"bankName": "JANATA BANK LTD",
		"bankCode": "JANBBDDH",
		"providerCode": "88090260000",
		"status": "ACTIVE"
	},
	{
		"bankName": "SBAC BANK LIMITED",
		"bankCode": "SBACBDDH",
		"providerCode": "88090430000",
		"status": "ACTIVE"
	},
	{
		"bankName": "SHAHJALAL ISLAMI BANK LTD",
		"bankCode": "SJBLBDDH",
		"providerCode": "88090440000",
		"status": "ACTIVE"
	},
	{
		"bankName": "SHIMANTO BANK LIMITED",
		"bankCode": "SHMTBDDD",
		"providerCode": "88090450000",
		"status": "ACTIVE"
	},
	{
		"bankName": "SOCIAL ISLAMI BANK LTD",
		"bankCode": "SOIVBDDH",
		"providerCode": "88090460000",
		"status": "ACTIVE"
	},
	{
		"bankName": "SONALI BANK LTD",
		"bankCode": "BSONBDDH",
		"providerCode": "88090470000",
		"status": "ACTIVE"
	},
	{
		"bankName": "SOUTHEAST BANK LTD",
		"bankCode": "SEBDBDDH",
		"providerCode": "88090480000",
		"status": "ACTIVE"
	},
	{
		"bankName": "STANDARD BANK LTD",
		"bankCode": "SDBLBDDH",
		"providerCode": "88090490000",
		"status": "ACTIVE"
	},
	{
		"bankName": "STANDARD CHARTERED BANK",
		"bankCode": "SCBLBDDX",
		"providerCode": "88090500000",
		"status": "ACTIVE"
	},
	{
		"bankName": "STATE BANK OF INDIA",
		"bankCode": "SBINBDDH",
		"providerCode": "88090510000",
		"status": "ACTIVE"
	},
	{
		"bankName": "THE CITY BANK LTD",
		"bankCode": "CIBLBDDH",
		"providerCode": "88090520000",
		"status": "ACTIVE"
	},
	{
		"bankName": "THE FARMERS BANK LIMITED",
		"bankCode": "FRMSBDDH",
		"providerCode": "88090530000",
		"status": "ACTIVE"
	},
	{
		"bankName": "THE PREMIER BANK LTD",
		"bankCode": "PRMRBDDH",
		"providerCode": "88090540000",
		"status": "ACTIVE"
	},
	{
		"bankName": "TRUST BANK LTD",
		"bankCode": "TTBLBDDH",
		"providerCode": "88090550000",
		"status": "ACTIVE"
	},
	{
		"bankName": "UNION BANK LTD",
		"bankCode": "UBLDBDDH",
		"providerCode": "88090560000",
		"status": "ACTIVE"
	},
	{
		"bankName": "UNITED COMMERCIAL BANK LTD",
		"bankCode": "UCBLBDDH",
		"providerCode": "88090570000",
		"status": "ACTIVE"
	},
	{
		"bankName": "UTTARA BANK LTD",
		"bankCode": "UTBLBDDH",
		"providerCode": "88090580000",
		"status": "ACTIVE"
	},
	{
		"bankName": "WOORI BANK",
		"bankCode": "HVBKBDDH",
		"providerCode": "88090590000",
		"status": "ACTIVE"
	},
	{
		"bankName": "EXIM BANK LTD",
		"bankCode": "EXBKBDDH",
		"providerCode": "88090180000",
		"status": "ACTIVE"
	},
	{
		"bankName": "COMMUNITY BANK",
		"bankCode": "COYMBDDD",
		"providerCode": "88090600000",
		"status": "ACTIVE"
	}			
}
				

Bank List request parameter list:

Parameter name Description Data Type Requirement Field Length
countryCode ISO Alpha 2 country code of the destination country. Eg. NG for Nigeria String Mandatory 2
lastUpdatedOn last updated date and time in YYYY-MM-DD HH:mm:ss.SSS format. String Mandatory 22
bankName Full name of the beneficiary bank String Mandatory 4-60
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 Mandatory 4-25
providerCode ● This is a code that indicates the bank to which the transaction is to be sent.
● If not set, then TerraPay will resolve the bank based on the 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.
Numeric Conditional 7-12
status Indicates the status of the account. If 'active' then the account can receive funds. If not then transactions sent to the account will fail.>/td> String Mandatory 6

Create A Business Transaction




This API is used to create business transaction. This is similar to create a transaction with additional parameters required to conduct business transaction. Business transactions can be as follows:

  1. Business to Business (B2B)
  2. Business to Person (B2P)
  3. Person to Business (P2B)
The URI format is: /transactions



B2B transaction to a 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: "2018-03-12 09:00:00"
X-ORIGINCOUNTRY:"FR"
		
{
	"currency": "NGN",
	"type": "b2b",
	"requestDate": "2020-01-02 10:51:16",
	"amount": "35500.00",
	"descriptionText": "Gift for my brother",
	"requestingOrganisationTransactionReference": "12345868378400387540",
	"sendingAmount": "35500.00",
	"payinCcyCode": "USD",
	"provider": "23401",
	"paymentMode": "cash",
	"authenticationPartnerCode": "4534",
	"paymentOption": "Mobile Wallet",
	"sendingPartnerCode": "343432223",
	"receivingPartnerCode": "343432223",
	"debitParty": [
	{
		"key": "msisdn",
		"value": "+4491509874561"
	} 
	],
		"creditParty": [
	{
		"key": "bankaccountno",
		"value": "1976010126"
	},
	{
		"key": "sortcode",
		"value": "CITINGLA"
	},
	{
		"key": "organisationid",
		"value": "Citi Bank"
	},
	{
		"key": "banksubcode",
		"value": "0001"
	},
	{
		"key": "bankBranchName",
		"value": "Citi Bank"
	},
	{
		"key": "accountName",
		"value": "Rajesh"
	},
	{
		"key": "accountIBAN",
		"value": "GB29NWBK60161331926819"
	},
	{
		"key": "accountAdditionalNo1",
		"value": "2656915085434"
	}
	],
		"senderKyc": {

	},
		"recipientKyc": {

	},
		"internationalTransferInformation": {
			"quoteId": "QT0FEO4OZZ28PLCA5",
			"receivingCountry": "NG",
			"remittancePurpose": "Advanced Goods Payments",
			"sourceOfFunds": "Savings"
	},
	"business": {
		"senderKyc": {
			"businessName": "sample business",
			"businessAddress1": "walton's road",
			"businessAddressCity": "Lyon",
			"businessAddressCountryCode": "US",
			"businessPrimaryContactCountryCode": "US",
			"businessPrimaryContactNo": "3472034605",
			"businessDescription": "Electronics",
			"businessCountryCode": "US",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "23123456789",
			"businessRegistrationIssueDate": "2020-09-26",
			"businessIDValidThru": "2033-09-26"
		},
		"recepientKyc": {
			"businessName": "Oyugi Randy Electric Sale Pvt. Ltd.",
			"businessPINCode": "123456",
			"businessAddress1": "24",
			"businessAddress2": "walton's road",
			"businessAddressCity": "newyork",
			"businessAddressState": "NYC",
			"businessAddressCountryCode": "NG",
			"businessAddressZip": "123456",
			"businessPrimaryContactCountryCode": "NG",
			"businessPrimaryContactNo": "232323212",
			"businessPrimaryContactNoType": "Mobile",
			"businessDescription": "Electronics wholesale",
			"businessEmail": "rs.electronics@gmail.com",
			"businessCountryCode": "NG",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "2312345678912",
			"businessRegistrationIssuedBy": "NYC_TRADE",
			"businessRegistrationIssuedAt": "NYC",
			"businessRegistrationIssueDate": "2002-08-26",
			"businessIDValidThru": "2036-09-26",
			"typeofbusiness": "Electronics",
			"businessPObox": "12345",
			"businessMobile": "343234433"
		}
	}	
}
		
		
																	

B2B transaction to 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"
		
{
	"currency": "NGN",
	"type": "b2b",
	"requestDate": "2020-01-02 10:51:16",
	"amount": "35500.00",
	"descriptionText": "Gift for my brother",
	"requestingOrganisationTransactionReference": "12345868378400387540",
	"sendingAmount": "35500.00",
	"payinCcyCode": "USD",
	"provider": "23401",
	"paymentMode": "cash",
	"authenticationPartnerCode": "4534",
	"paymentOption": "Mobile Wallet",
	"sendingPartnerCode": "343432223",
	"receivingPartnerCode": "343432223",
	"debitParty": [
	{
		"key": "msisdn",
		"value": "+4491509874561"
	} 
	],
		"creditParty": [
	{
		"key": "msisdn",
		"value": "+2349061114853"
	}
	],
		"senderKyc": {

	},
		"recipientKyc": {
	},
		"internationalTransferInformation": {
			"quoteId": "QT0FEO4OZZ28PLCA5",
			"receivingCountry": "NG",
			"remittancePurpose": "Advanced Goods Payments",
			"sourceOfFunds": "Savings"
	},
	"business": {
		"senderKyc": {
			"businessName": "sample business",
			"businessAddress1": "walton's road",
			"businessAddressCity": "Lyon",
			"businessAddressCountryCode": "US",
			"businessPrimaryContactCountryCode": "US",
			"businessPrimaryContactNo": "3472034605",
			"businessDescription": "Electronics",
			"businessCountryCode": "US",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "23123456789",
			"businessRegistrationIssueDate": "2020-09-26",
			"businessIDValidThru": "2033-09-26"
		},
		"recepientKyc": {
			"businessName": "Oyugi Randy Electric Sale Pvt. Ltd.",
			"businessPINCode": "123456",
			"businessAddress1": "24",
			"businessAddress2": "walton's road",
			"businessAddressCity": "newyork",
			"businessAddressState": "NYC",
			"businessAddressCountryCode": "NG",
			"businessAddressZip": "123456",
			"businessPrimaryContactCountryCode": "NG",
			"businessPrimaryContactNo": "232323212",
			"businessPrimaryContactNoType": "Mobile",
			"businessDescription": "Electronics wholesale",
			"businessEmail": "rs.electronics@gmail.com",
			"businessCountryCode": "NG",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "2312345678912",
			"businessRegistrationIssuedBy": "NYC_TRADE",
			"businessRegistrationIssuedAt": "NYC",
			"businessRegistrationIssueDate": "2002-08-26",
			"businessIDValidThru": "2036-09-26",
			"typeofbusiness": "Electronics",
			"businessPObox": "12345",
			"businessMobile": "343234432"
		}
	}	
}

		

B2P 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:"FR"

{
	"currency": "NGN",
	"type": "b2p",
	"requestDate": "2020-01-02 10:51:16",
	"amount": "35500.00",
	"descriptionText": "Gift for my brother",
	"requestingOrganisationTransactionReference": "123458w8378400387553",
	"sendingAmount": "35500.00",
	"payinCcyCode": "USD",
	"provider": "23401",
	"paymentMode": "cash",
	"authenticationPartnerCode": "4534",
	"paymentOption": "Mobile Wallet",
	"sendingPartnerCode": "343432223",
	"receivingPartnerCode": "343432223",
	"debitParty": [
	{
		"key": "msisdn",
		"value": "+4491509874561"
	} 
	],
		"creditParty": [
	{
		"key": "bankaccountno",
		"value": "1976010126"
	},
	{
		"key": "sortcode",
		"value": "CITINGLA"
	},
	{
		"key": "organisationid",
		"value": "Citi Bank"
	},
	{
		"key": "banksubcode",
		"value": "0001"
	},
	{
		"key": "bankBranchName",
		"value": "Citi Bank"
	},
	{
		"key": "accountName",
		"value": "Rajesh"
	},
	{
		"key": "accountIBAN",
		"value": "GB29NWBK60161331926819"
	},
	{
		"key": "accountAdditionalNo1",
		"value": "2656915085434"
	}
	],
		"senderKyc": {
			
	},
	"recipientKyc":{
		"primaryContactCountryCode": "NG",
		"primaryContactNo": "2349061114853",
		"primaryContactNoType": "personal",
		"subjectName":{
			"firstName": "oyugi",
			"lastName": "randy",
			"fullName": "oyugi randy"
		}
	},
   		"internationalTransferInformation":{
			"quoteId": "QT0FEO4UG99LQNQC3",
			"receivingCountry": "NG",
			"remittancePurpose": "Business Travel",
			"sourceOfFunds": "Business Income",
			"relationshipSender": "Employer"
	},
	"business": {
		"senderKyc": {
			"businessName": "sample business",
			"businessAddress1": "alton's road",
			"businessAddressCity": "Lyon",
			"businessAddressCountryCode": "US",
			"businessPrimaryContactCountryCode": "US",
			"businessPrimaryContactNo": "3472034605",
			"businessDescription": "Electronics",
			"businessCountryCode": "US",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "23123456789",
			"businessRegistrationIssueDate": "2001-09-26",
			"businessIDValidThru": "2033-09-26"
		},
		"recepientKyc": {

 		}
	}
}


B2P transaction to 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: "2019-08-25 12:00:00"
X-ORIGINCOUNTRY:"FR"

{
	"currency": "NGN",
	"type": "b2p",
	"requestDate": "2020-01-02 10:51:16",
	"amount": "35500.00",
	"descriptionText": "Gift for my brother",
	"requestingOrganisationTransactionReference": "123458w8378400387553",
	"sendingAmount": "35500.00",
	"payinCcyCode": "USD",
	"provider": "23401",
	"paymentMode": "cash",
	"authenticationPartnerCode": "4534",
	"paymentOption": "Mobile Wallet",
	"sendingPartnerCode": "343432223",
	"receivingPartnerCode": "343432223",
	"debitParty": [
	{
		"key": "msisdn",
		"value": "+4491509874561"
	} 
	],
	"creditParty": [
		{
		"key": "msisdn",
		"value": "+2349061114853"
		}
	],
		"senderKyc": {
			
	},
	"recipientKyc":{
		"primaryContactCountryCode": "NG",
		"primaryContactNo": "2349061114853",
		"primaryContactNoType": "personal",
		"subjectName":{
			"firstName": "Kevin",
			"lastName": "Hawkins",
			"fullName": "Kevin Hawkins"
		}
	},
   		"internationalTransferInformation":{
			"quoteId": "QT0FEO4UG99LQNQC3",
			"receivingCountry": "NG",
			"remittancePurpose": "Business_Travel",
			"sourceOfFunds": "Business_Income",
			"relationshipSender": "Employer"
	},
	"business": {
		"senderKyc": {
			"businessName": "sample business",
			"businessAddress1": "alton's road",
			"businessAddressCity": "Lyon",
			"businessAddressCountryCode": "US",
			"businessPrimaryContactCountryCode": "US",
			"businessPrimaryContactNo": "3472034605",
			"businessDescription": "Electronics",
			"businessCountryCode": "US",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "23123456789",
			"businessRegistrationIssueDate": "2001-09-26",
			"businessIDValidThru": "2033-09-26"
		},
		"recepientKyc": {

 		}
	}
}


P2B 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:"FR"

{
	"currency": "NGN",
	"type": "p2b",
	"requestDate": "2020-01-02 10:51:16",
	"amount": "35500.00",
	"descriptionText": "Gift for my brother",
	"requestingOrganisationTransactionReference": "123458w8378400387553",
	"sendingAmount": "35500.00",
	"payinCcyCode": "USD",
	"provider": "23401",
	"paymentMode": "cash",
	"authenticationPartnerCode": "4534",
	"paymentOption": "Mobile Wallet",
	"sendingPartnerCode": "343432223",
	"receivingPartnerCode": "343432223",
	"debitParty": [
	{
		"key": "msisdn",
		"value": "+4491509874561"
	} 
	],
		"creditParty": [
	{
		"key": "bankaccountno",
		"value": "1976010126"
	},
	{
		"key": "sortcode",
		"value": "CITINGLA"
	},
	{
		"key": "organisationid",
		"value": "Citi Bank"
	},
	{
		"key": "banksubcode",
		"value": "0001"
	},
	{
		"key": "bankBranchName",
		"value": "Citi Bank"
	},
	{
		"key": "accountName",
		"value": "Rajesh"
	},
	{
		"key": "accountIBAN",
		"value": "GB29NWBK60161331926819"
	},
	{
		"key": "accountAdditionalNo1",
		"value": "2656915085434"
	}
	],
	"senderKyc": {
		"nationality": "US",
		"dateOfBirth": "1986-06-28",
		"gender": "M",
		"primaryContactCountryCode": "NG",
		"primaryContactNo": "2349061114853",
		"primaryContactNoType": "personal",
		"idDocument": [
			{
				"idType": "nationalidcard",
				"idNumber": "123456789",
				"issueDate": "2003-09-26",
				"expiryDate": "2033-09-26",
				"issuerCountry": "US"
			}
		],
		"postalAddress": {
			"addressLine1": "49",
			"addressLine2": "park street",
			"addressLine3": "walton's road",
			"city": "Lyon",
			"stateProvince": "Lyon",
			"postalCode": "123456",
			"country": "US"
		},
		"subjectName": {
			"title": "Mr.",
			"firstName": "Einstein",
			"middleName": "James",
			"lastName": "Bela",
			"fullName": "Einstien James Bela"
		}
	},
	"recipientKyc":{

	},
	"internationalTransferInformation":{
		"quoteId": "QT0FEO4TUIMN33Z6B",
		"receivingCountry": "NG",
		"remittancePurpose": "Business profits to Parents",
		"sourceOfFunds": "Savings",
		"relationshipSender": "Brother"
	},
	"business": {
		"senderKyc": {

		},
		"recepientKyc": {
			"businessName": "Oyugi Randy Electric Sale Pvt. Ltd.",
			"businessPINCode": "123456",
			"businessAddress1": "24",
			"businessAddress2": "walton's road",
			"businessAddressCity": "newyork",
			"businessAddressState": "NYC",
			"businessAddressCountryCode": "NG",
			"businessAddressZip": "123456",
			"businessPrimaryContactCountryCode": "NG",
			"businessPrimaryContactNo": "232323212",
			"businessPrimaryContactNoType": "Mobile",
			"businessDescription": "Electronics wholesale",
			"businessEmail": "vrs.electronics@gmail.com",
			"businessCountryCode": "NG",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "2312345678912",
			"businessRegistrationIssuedBy": "NYC_TRADE",
			"businessRegistrationIssuedAt": "NYC",
			"businessRegistrationIssueDate": "2002-09-26",
			"businessIDValidThru": "2036-09-26",
			"typeofbusiness": "Electronics",
			"businessPObox": "12345",
			"businessMobile": "343234433"
		}
	}
}


P2B transaction to 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: "2019-08-25 12:00:00"
X-ORIGINCOUNTRY:"FR"

{
	"currency": "NGN",
	"type": "p2b",
	"requestDate": "2020-01-02 10:51:16",
	"amount": "35500.00",
	"descriptionText": "Gift for my brother",
	"requestingOrganisationTransactionReference": "123458w8378400387553",
	"sendingAmount": "35500.00",
	"payinCcyCode": "USD",
	"provider": "23401",
	"paymentMode": "cash",
	"authenticationPartnerCode": "4534",
	"paymentOption": "Mobile Wallet",
	"sendingPartnerCode": "343432223",
	"receivingPartnerCode": "343432223",
	"debitParty": [
	{
		"key": "msisdn",
		"value": "+4491509874561"
	} 
	],
		"creditParty": [
	{
		"key": "msisdn",
		"value": "+2349061114853"
	}
	],
	"senderKyc": {
		"nationality": "US",
		"dateOfBirth": "1986-06-28",
		"gender": "M",
		"primaryContactCountryCode": "NG",
		"primaryContactNo": "2349061114853",
		"primaryContactNoType": "personal",
		"idDocument": [
			{
				"idType": "nationalidcard",
				"idNumber": "123456789",
				"issueDate": "2003-09-26",
				"expiryDate": "2033-09-26",
				"issuerCountry": "US"
			}
		],
		"postalAddress": {
			"addressLine1": "49",
			"addressLine2": "park street",
			"addressLine3": "walton's road",
			"city": "Lyon",
			"stateProvince": "Lyon",
			"postalCode": "123456",
			"country": "US"
		},
		"subjectName": {
			"title": "Mr.",
			"firstName": "Einstein",
			"middleName": "James",
			"lastName": "Bela",
			"fullName": "Einstien James Bela"
		}
	},
	"recipientKyc":{

	},
	"internationalTransferInformation":{
		"quoteId": "QT0FEO4TUIMN33Z6B",
		"receivingCountry": "NG",
		"remittancePurpose": "Business profits to Parents",
		"sourceOfFunds": "Savings",
		"relationshipSender": "Brother"
	},
	"business": {
		"senderKyc": {

		},
		"recepientKyc": {
			"businessName": "Oyugi Randy Electric Sale Pvt. Ltd.",
			"businessPINCode": "123456",
			"businessAddress1": "24",
			"businessAddress2": "walton's road",
			"businessAddressCity": "newyork",
			"businessAddressState": "NYC",
			"businessAddressCountryCode": "NG",
			"businessAddressZip": "123456",
			"businessPrimaryContactCountryCode": "NG",
			"businessPrimaryContactNo": "232323212",
			"businessPrimaryContactNoType": "Mobile",
			"businessDescription": "Electronics wholesale",
			"businessEmail": "vrs.electronics@gmail.com",
			"businessCountryCode": "NG",
			"businessRegistrationType": "Private Limited Company",
			"businessRegistrationNumber": "2312345678912",
			"businessRegistrationIssuedBy": "NYC_TRADE",
			"businessRegistrationIssuedAt": "NYC",
			"businessRegistrationIssueDate": "2002-09-26",
			"businessIDValidThru": "2036-09-26",
			"typeofbusiness": "Electronics",
			"businessPObox": "12345",
			"businessMobile": "343234433"
		}
	}
}


Business transaction request parameter list:

Business 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 value - b2b, b2p, p2b 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 sent in the validation request. If a different value is sent then the transaction will be rejected. Mandatory provider code for China Union Pay is CNUNIONPAY. Mandatory provider code for Philippines Direct to bank transfer is PH_DIRECT_TO_BANK.
NOTE:
● Mandatory for wallet transactions to China, Bangladesh, Indonesia, Nepal, Pakistan, Philippines, South Sudan, Togo, Vietnam, Cambodia, Columbia & Haiti.
● Optional for other countries.
Numeric Optional 5-12
sendingAmount Payin Amount with precision of 2 decimal places String Mandatory
payingCcyCode Payin Currency in ISO 4217 format. Eg. USD String Mandatory
paymentMode Type of Payment i.e. Cash, Debit, Account or Others String Mandatory
authenticationPartnerCode Multi Factor Authentication Partner Code String Mandatory
paymentOption Mobile Wallet/Account Credit String Mandatory
sendingPartnerCode Unique Send Partner Code String Mandatory
recievingPartnerCode Unique Receive Partner Code String Optional
debitParty:
key msisdn String Mandatory 6
value Sender Mobile Number with country code. Eg. +91xxxxxxxxxx String Mandatory 10-18
creditParty:
Key msisdn String Mandatory 6
Value Beneficiary wallet Number with country code. Eg.+91xxxxxxxxxx. String Optional - For Bank Accounts
Mandatory - For Mobile Wallet
5-50
Key beneficiarySmsNotify Optional
Value Status Update through SMS notification. true indicates ntofication required. Notification will be sent for b2b and p2b transactions on BusinessMsisdn number (part of business receipient kyc)
Key bankaccountno String Conditional 13
Value Recieve Bank Account 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 wallets
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
Key banksubcode String Conditional 1-10
Value This is a code that indicates the branch code of the specific bank to which the transaction is to be sent.
NOTE:
● Mandatory for bank transactions to Brazil & Uruguay.
● Optional for other countries.
● If the transaction is to Bangladesh then partner can send rounting number in banksubcode and they do not have to send the provider code.
String Mandatory - For bank accounts
Optional - For mobile wallets
1-10
Key accountIBAN Conditional
Value Recieve Account IBAN Number for receiving funds Mandatory - For bank accounts
Optional - For mobile wallets
Key accountAdditionalNo1 Conditional
Value Account Number Additional field 1 Mandatory - For bank accounts
Optional - For mobile wallets
Key accountAdditionalNo2
Value Account Number Additional field 2
senderKyc: This section of sender person kyc is applicable for p2b business transactions
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
primaryContactCountryCode Primary Contact Country Code String Mandatory
primaryContactNo Primary Contact Number String Mandatory
primaryContactNoType Primary Contact Number type i.e. Personal/Office String Mandatory
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 Optional 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format. String Mandatory 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 Optional 4-20
postalCode Postal Code of sender's address String Optional 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: This section of recepient person kyc is applicable for b2p business transactions
nationality
primaryContactCountryCode Primary Contact Country Code String Optional
primaryContactNo Primary Contact Number String Optional
primaryContactNoType Primary Contact Number type i.e. Personal/Office String Optional
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
recipientKyc:idDocument:
idType Customer's Id document type:
nationalidcard
drivinglicense
passport
String Optional 1-20
idNumber Customer's Id number
For any other type, it should be Passport Number,Document number. Eg. M123456,123434567
String Optional 1-30
issueDate Customer's Id document issue date in YYYY-MM-DD format. String Optional 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
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. Click here to find the accepted values. String Mandatory 4-30
sourceOfFunds Source of funds. String Mandatory 4-17
relationshipSender The relation between the sender and the beneficiary. String Mandatory 3-11
businesssenderKyc: This section of sender business kyc is applicable for b2p and b2b business transactions.
businessName Company Name String Mandatory
businessPINCode Company Pin Code String Optional
businessAddress1 Registered Address 1 String Mandatory
businessAddress2 Registered Address 2 String Optional
businessAddressCity Registered City String Optional
businessAddressCountryCode Registered Country Code String Optional
businessAddressZip Registered address Zip Code String Optional
businessPrimaryContactCountryCode Company Primary Contact Country Code String Mandatory
businessPrimaryContactNo Company Primary Contact Number String Mandatory
businessDescription Type of Company String Optional
businessEmail Company email id String Mandatory
businessCountryCode Company Country Code String Mandatory
businessRegistrationType Type of Registration String Mandatory
businessRegistrationIssuedBy Company Incorporation Issued by String Optional
businessRegistrationIssuedAt Company Incorporation Issued at String Optional
businessRegistrationNumber Company Incorporation Number String Mandatory
businessRegistrationIssueDate Company Incorporation Issued Date String Mandatory
businessIDValidThru Company Incorporation Expiry Date String Mandatory
recipientKyc:
business Name Company Name String Mandatory
businessPINCode Company Pin Code String Optional
businessAddress1 Registered Address 1 String Optional
businessAddress2 Registered Address 2 String Optional
businessAddressCity Registered City String Optional
businessAddressState Registered State String Optional
businessAddressCountryCode Registered Country Code String Mandatory
businessAddressZip Registered address Zip Code String Optional
businessPrimaryContactCountryCode Company Primary Contact Country Code String Optional
businessPrimaryContactNo Company Primary Contact Number String Optional
businessPrimaryContactNoType Company Primary Contact Number type i.e. Personal/Office String Optional
businessDescription Type of Company String Optional
businessEmail Company email id String Optional
businessCountryCode Company Country Code String Optional
businessRegistrationType Type of Registration String Optional
businessRegistrationNumber Company Incorporation Number String Optional
businessRegistrationIssuedBy Company Incorporation Issued by String Optional
businessRegistrationIssuedAt Company Incorporation Issued at String Optional
businessRegistrationIssueDate Company Incorporation Issued Date String Optional
businessIDValidThru Company Incorporation Expiry Date String Optional
typeofbusiness Type of Company String Optional
business PO box Company PO Box String Optional


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).
1061 Destination Country Sanctioned. No Cancel Destination country is on sanction list . Transaction cannot be delievered.
1062 Source Country Sanctioned. No Cancel Source country is on sanctionlist. Transaction cannot be delievered.
1073 Routing Failed. Yes Retry Route is inactive. Check with TerraPay operations team to enable the route and retry.
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.
3011 Invalid Fx Rate Yes Retry Check with TerraPay operations on the Fx rate configuration.
3022 Corridor validation failed Yes Retry Operation team needs to check the corr configuration.
3027 Server is busy. Please try after sometime Yes Retry Check with TerraPay technical team before retry.
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.
3049 Remit Failed. Insufficient funds No Retry Check your balance at TerraPay and retry after balance is funded.
3060 Beneficiary daily transaction count limit reached No Cancel Beneficiary has reached the daily transaction count.
3061 Beneficiary weekly transaction count limit reached No Cancel Beneficiary has reached the weekly transaction count.
3062 Beneficiary monthly transaction count limit reached No Cancel Beneficiary has reached the monthly transaction count.
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.
3117 Transfer type not supported No Cancel Please check th transfer type and retry the transaction with the correct Transfer type
3132 Remit Failed - Max retry limit reached. No Cancel Transaction failed as transaction limit exceeded.
3222 Invalid UPI amount. No Cancel The provided amount is not acceptable for UPI transaction.
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.

Purpose, Source of Funds, and Relationship



Person to Person



P2P Purpose for Transaction
Sl. no. Purpose
1 Business Profits to Parents
2 Business Travel
3 Family Maintenance
4 Salary
5 Savings
6 Medical Expenses
7 Tution Fees
8 Education Support
9 Gift

P2P Source of Funds
Sl. no. Source of Funds Proof
1 Salary
    Latest Bank statement
    ATM Withdrawal slip
    Loan Agreement
2 Savings
3 Lottery
4 Loan
5 Business Income
6 Others

P2P Relationship
Sl. no. Relationship
1 Self
2 Father
3 Mother
4 Spouse
5 Son
6 Daughter
7 Brother
8 Sister
9 Friend
10 Employer
11 Colleague

Person to Business



P2B Purpose for Transaction
Sl. no. Purpose
1 Advanced Goods Payments
2 Business profits to Parents
3 Business Travel
4 Charitable Donation
5 Conference or Training Fee
6 Employee Compensation
7 Events or Competition Participation Expenses
8 Export Goods Payments
9 Goods and Services
10 Goods Exported
11 Loan Repayment
12 Other Business
13 Other Business Services
14 Rent Property Expenses
15 Salary Payment
16 Software Export
17 Travel Cost Accomodation Cost
18 Travel Expenses
P2B Source of Funds
Sl. no. Source of Funds Proof
1 Salary
    Audited Financials
    Loan Agreement
    Invoice Copy
    Latest Bill
2 Savings
3 Lottery
4 Loan
5 Business Income
6 Business Profit
7 Settlement
8 Others

Business to Person



B2P Purpose for Transaction
Sl. no. Purpose
1 Advanced Goods Payments
2 Business profits to Parents
3 Business Travel
4 Charitable Donation
5 Conference or Training Fee
6 Employee Compensation
7 Events or Competition Participation Expenses
8 Export Goods Payments
9 Goods and Services
10 Goods Exported
11 Loan Repayment
12 Other Business
13 Other Business Services
14 Rent Property Expenses
15 Salary Payment
16 Software Export
17 Travel Cost Accomodation Cost
18 Travel Expenses
B2P Source of Funds
Sl. no. Source of Funds Proof
1 Salary
    Audited Financials
    Loan Agreement
    Invoice Copy
    Latest Bill
2 Savings
3 Lottery
4 Loan
5 Business Income
6 Business Profit
7 Settlement
8 Others

Business to Business



B2B Purpose for Transaction
Sl. no. Purpose
1 Advanced Goods Payments
2 Business profits to Parents
3 Business Travel
4 Charitable Donation
5 Conference or Training Fee
6 Employee Compensation
7 Events or Competition Participation Expenses
8 Export Goods Payments
9 Goods and Services
10 Goods Exported
11 Loan Repayment
12 Other Business
13 Other Business Services
14 Rent Property Expenses
15 Salary Payment
16 Software Export
17 Travel Cost Accomodation Cost
18 Travel Expenses
B2B Source of Funds
Sl. no. Source of Funds Proof
1 Salary
    Audited Financials
    Loan Agreement
    Invoice Copy
    Latest Bill
2 Savings
3 Lottery
4 Loan
5 Business Income
6 Business Profit
7 Settlement
8 Others

About


TerraPay is a licensed digital payments infrastructure and solutions provider, paving the global payments highway.
For more information about us, click here: https://www.terrapay.com/about-us.html