Introduction


Purpose


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


Scope


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


Audience


This document is to be used by

  • TerraPay Integrations technical team
  • Partner Integrations technical team


Abbreviations, Acronyms & Definitions


AML Anti Money Laundering
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
FOREX Foreign Exchange Rate
SRC Source
DST Destination
MSISDN Mobile Station International Subscriber Directory Number
AWS Amazon Web Services
DMZ De Militarized Zone
RDS Relational Database Service (AWS)
REST REpresentational State Transfer
MNP Mobile number portability
GSMA GSM Association

Assumptions


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


Connectivity, Staging & Production


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

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

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

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


Services


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

  1. Remit to Mobile
  2. Remit to Bank
  3. Over the Counter (OTC) cash pickup


Remit to Mobile


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

The sender can initiate the money transfer from a wallet, bank account or by cash over the counter at a partner agent outlet.




Remit to Bank


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



Over the counter (OTC) Cash pickup


This service enables the sender to send money to the beneficiary as cash pickup. The sender will receive a Transaction Code. The sender has to share this Transaction code with the beneficiary. The beneficiary will then have to go to a partner agent outlet with identification documents and this Transaction code to pick up the money as cash
The sender can initiate the money transfer from a wallet, bank account or by cash over the counter at a partner agent outlet. Once the transaction is sucessfully completed, a Transaction Code will be provided to the sender that needs to be shared with the beneficiary.



GSMA APIs


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

Basic Transaction Steps

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

X-USERNAME, X-PASSWORD values will be shared with the Partner during onboarding on test and production environment seperately.
X-PASSWORD must be hashed using SHA2 and then sent in the API request.

Inbound APIs


ViewAccountStatus


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

The Accounts Status API returns a harmonised status of the account. The status enables the client to determine whether transactions can be subsequently posted against the account. URI format is:

/accounts/{Account Identifiers}/status

View Account Status of a Mobile Wallet

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

HTTP Request
GET /eig/gsma/accounts/+234xxxxxxxxx/status?bnv=John%20Smith HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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 Type Optional Field Length
msisdn Beneficiary MSISDN. This corresponds to the mobile wallet to which funds are to be transferred. Eg. +91xxxxxxxxxx String No 10-18
bnv Full KYC name of the beneficiary as registered with the wallet provider. String No 1-50

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}

HTTP Request
GET /eig/gsma/accounts/232698745623/status?bnv=John%20Smith&bankcode=CITIZAJXHUB&CITIBANK%20SOUTH%20AFRICA&country=US HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
X-DATE: "2017-05-03 11:00:00"
{
 "error": 
 {
    "errorCategory":"businessRule", 
    "errorCode":"6008", 
    "errorDescription":"Beneficiary name does not match", 
    "errorDateTime":"2017-05-02 11:00:00", 
 }
}

															

Request Paramters

Parameter name Description Type Optional Field Length
accountId Beneficiary Bank Account or IBAN Number as applicable in the destination country for receiving funds. Eg. 2365417895. String No 5-50
bnv Full KYC name of the beneficiary as registered with the bank. String No 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 Yes 4-25
bankname Full name of the beneficiary bank String No 4-60
country ISO Alpha 2 country code of the destination country. Eg. NG for Nigeria String No 2
msisdn Beneficiary phone number in countries where is it mandatory for bank transfers. Eg. +91xxxxxxxxxx String Yes 10-18

Response Parameters

Parameter name Description Type Validation
status Indicates a simplified representation of the account status. This will be shown as 'available' or 'available'. A state of 'unavailable' means that the account is in a state that does not allow posting of transactions. Unregistered indicates that although not available, a transaction posted with the account identifier(s) will result an unregistered voucher creation. String Enumeration = available, unavailable, unregistered
subStatus Property can be used to return a provider-specific status for the account./td> String
lei Indicates the Legal Entity Identifier of the organisation holding the account. String Length = 20, Regular Expression

CreateAQuotation


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

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

/quotations

Create a Quotation to Mobile Wallet

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

HTTP Request
POST /eig/gsma/quotations HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

{
"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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

{
"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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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 Type Optional Field Length
requestDate The creation date and time of the transaction as supplied by the client in YYYY-MM-DD HH:mm:ss DateTime No 19
requestAmount Requested quotation amount with precision of 2 decimal places String No 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 No 3
debitParty:
key msisdn String Yes 6
value Sender Mobile Number Eg. +91xxxxxxxxxx String Yes 10-18
creditParty:
Key msisdn String C 6
Value Beneficiary Mobile Number Eg. +91xxxxxxxxxx. String Yes - For Bank Accounts
No - For Mobile Wallet
10-18
Key bankaccountno String C 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 No - For Bank Accounts
Yes - For Mobile Wallet
5-50
Key receivingCountry String C 16
Value Destination Country. Eg. NG.
This key/value pair is optional if the transfer is to a mobile wallet.
String No - For Bank Accounts
Yes - For Mobile Wallet
5-50
quotes:
sendingCurrency Currency of the debitor in ISO 4217 format. Eg. EUR String No 3
receivingCurrency Currency of the creditor in ISO 4217 format. Eg. NGN
This field is optional. If not provided, the default currency supported in the destination coutry will be used for calculating the quote.
String Yes 3

Create quotation response parameter list:

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

CreateATransaction


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

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

/transactions

Create a transaction to a Mobile Wallet

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

HTTP Request
POST /eig/gsma/transactions HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

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

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

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

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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 Type Optional 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 No 19
amount Destination amount payable to the beneficiary with precision of 2 decimal places. String No 10,2
currency Destination amount currency in ISO 4217 format. Eg. NGN String No 3
type The harmonized Transaction Type. Fixed default value "inttransfer" String No 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 Yes 0-20
requestingOrganisationTransactionReference Unique Transaction reference generated by the sending partner. String No 4-50
debitParty:
key msisdn String No 6
value Sender Mobile Number Eg. +91xxxxxxxxxx String No 10-18
creditParty:
Key msisdn String C 6
Value Beneficiary Mobile Number Eg. +91xxxxxxxxxx. String Yes - For Bank Accounts
No - For Mobile Wallet
10-18
Key bankaccountno String C 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 No - For Bank Accounts
Yes - For Mobile Wallet
5-50
Key sortcode String C 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 No - For mobile wallets
Yes - For bank accounts
4-25
Key organisationid String C 14
Value Full name of the beneficiary bank String No - For mobile wallets
Yes - For bank accounts
4-60
senderKyc:
nationality Nationality of the customer in ISO Alpha-2 format. Eg. US String No 2
dateOfBirth Customer's Date of Birth in YYYY-MM-DD format String No 10
gender Customer's Gender. Enumeration = (M)ale, (F)emale, (U)nspecified String Yes 1
senderKyc:idDocument:
idType Customer's Id document type:
nationalidcard
drivinglicense
passport
String No 1-20
idNumber Customer's Id number.
For any other type, it should be Passport Number,Document number. Eg. M123456,123434567
String No 1-30
issueDate Customer's Id document issue date in YYYY-MM-DD format.
String No 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format.
String Yes 10
issuerCountry Country where the identification type was issued in ISO Alpha-2 format. String Yes 2
senderKyc:postalAddress:
addressLine1 First line of the address String No 4-20
addressLine2 Second line of the address String Yes 4-20
addressLine3 Third line of the address String No 4-20
city City/Town of sender's address String No 4-20
stateProvince State of sender's address String No 4-20
postalCode Postal Code of sender's address String No 6-8
country Country in ISO Alpha-2 format String No 2
senderKyc:subjectName:
title Title of the Sender String Yes 0-6
firstName First name of the Sender String No 1-20
middleName Middle name of the Sender String Yes 0-50
lastName Last name of the Sender String No 1-20
fullName Full name of the Sender String No 1-50
recipientKyc:subjectName:
firstName First name of the recipient String No 1-20
lastName Last name of the recipient String No 1-20
fullName Full name of the recipient String No 1-50
internationalTransferInformation:
quoteId The specific quoteId to be used for the transaction. String No 16-20
receivingCountry Destination Country of international remittance in ISO Alpha 2 format. Eg. NG String No 2
remittancePurpose Reason for the transfer. Eg Gifts, Family expenses, etc String No 0-20

Create transaction response parameter list:

Parameter name Description 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 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

ViewATransaction


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

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

View Transaction Status to a Mobile Wallet

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

HTTP Request
GET /eig/gsma/transactions/TPKM000000056269 HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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 Type Optional
transactionReference Unique reference for the transaction. This is returned in the response by Terrapay's system String No

View transaction response parameter list:

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

Ledger Balance


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

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

Get Balance of all ledgers.

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

HTTP Request
GET /eig/gsma/accounts/all/balance HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

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

                                                            

Outbound APIs


ViewAccountStatus


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

The Accounts Status API returns a harmonised status of the account. The status enables the client to determine whether transactions can be subsequently posted against the account. This is primarily used for two reasons:
1. To check if the account to which the transfer is being made is KYC'ed as per regulation, is active and can receive incoming international transfers.
2. To check if the name registered on the account matches the name as provided by the sender party.
URI format is:
/accounts/{Account Identifiers}/status

View Account Status of a Mobile Wallet

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

HTTP Request
GET /eig/gsma/accounts/+234xxxxxxxxx/status?bnv=John%20Smith HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
X-DATE: "2017-05-03 11:00:00"
{
 "status":"available", 
 "subStatus":"6000:Beneficiary MSISDN Validation Success", 
 "lei":"",
 "recipientKyc": {
     "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"
    }
  }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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"
  }
}

															

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}

HTTP Request
GET /eig/gsma/accounts/232698745623/status?bnv=John%20Smith&bankcode=CITIUSJXHUB&CITIBANK%20SOUTH%20AFRICA&country=US HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
X-DATE: "2017-05-03 11:00:00"
{
 "status":"available", 
 "subStatus":"6000:Beneficiary MSISDN Validation Success", 
 "lei":"", 
 "recipientKyc": {
     "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"
    }
  }
}

HTTP Response - Failure
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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"
  }
}

															

View Account Status Request Paramter List

Parameter name Description Type Optional Field Length
bnv Full name of the beneficiary as registered in the mobile wallet or bank account String No 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
String No 4-25
bankname Full name of the beneficiary bank String No 4-25
country ISO Alpha -2 country code of the receiving bank. Eg. NG for Nigeria String No 2
msisdn Beneficiary phone number in corridors where is it mandatory for bank transfers. Eg. +91xxxxxxxxxx String Yes 10-18

View account status response parameter list:

Parameter name Description Type Validation
status Indicates a simplified representation of the account status. This will be shown as 'available' or 'available'. A state of 'unavailable' means that the account is in a state that does not allow posting of transactions. Unregistered indicates that although not available, a transaction posted with the account identifier(s) will result an unregistered voucher creation. String Enumeration = available, unavailable, unregistered
subStatus Property can be used to return a provider-specific status for the account./td> String
lei Indicates the Legal Entity Identifier of the organisation holding the account. String Length = 20, Regular Expression
recipientKyc:
nationality Nationality of the customer in ISO Alpha-2 format. Eg. US String No 2
dateOfBirth Customer's Date of Birth in YYYY-MM-DD format String No 10
gender Customer's Gender. Enumeration = (m)ale, (f)emale, (u)nspecified String No 1
recipientKyc:idDocument:
idType Customer's Id document type:
nationalidcard
drivinglicense
passport
String No 20
idNumber Customer's Id number.
For any other type, it should be Passport Number,Document number. Eg. M123456,123434567
String No 6-30
issueDate Customer's Id document issue date in YYYY-MM-DD format.
String No 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format.
String Yes 10
issuerCountry Country where the identification type was issued in ISO Alpha-2 format. String Yes 2
recipientKyc:postalAddress:
addressLine1 First line of the address String Np 4-20
addressLine2 Second line of the address String Yes 4-20
addressLine3 Third line of the address String No 4-20
city City/Town of receiver's address String No 4-20
stateProvince State of receiver's address String No 4-20
postalCode Postal Code of receiver's address String No 6-8
country Country in ISO Alpha-2 format String No 2
receiverKyc:subjectName:
title Title of the Receiver String Yes 0-6
firstName First name of the Receiver String No 2-20
middleName Middle name of the Receiver String Yes 0-50
lastName Last name of the Receiver String No 2-20
fullName Full name of the Receiver String No 2-50

CreateATransaction


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

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

/transactions

Create a transaction to a Mobile Wallet

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

HTTP Request
POST /eig/gsma/transactions HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "descriptionText": "Gift for my brother",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+33472034605"
    } 
   ],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    }
   ],
   "senderKyc": {
     "subjectName": {
       "firstName": "Einstein",
       "lastName": "Bela",
       "fullName": "Einstien James Bela"
    }
  },
   "recipientKyc": {
     "subjectName": {
      "firstName": "John",
      "lastName": "Smith",
      "fullName": "John Dave Smith"
    }
   },
   "internationalTransferInformation": {
     "quoteId": "QT037fQXs3LGWXea4",
     "receivingCountry": "NG",
     "remittancePurpose": "Gift"
  }
}

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

{
   "amount": "100000.01",
   "currency": "NGN",
   "type": "inttransfer",
   "descriptionText": "Gift for my brother",
   "requestDate": "2017-03-20T06:19:36.969Z",
   "requestingOrganisationTransactionReference": "partnerRefId1234",
   "debitParty": [
    {
       "key": "msisdn",
       "value": "+27123456789"
    },
    {
       "key": "kycId",
       "value": "KZA0000000000010"
    }  
	],
   "creditParty": [
    {
       "key": "msisdn",
       "value": "+23410706056"
    },
     {
      "key": "bankaccountno",
      "value": "2356915085237"
    },
     {
      "key": "sortcode",
      "value": "HDFC0002356"
    },
     {
      "key": "organisationid",
      "value": "HDFCBANK"
    }
  ],
   "senderKyc": {
     "subjectName": {
       "firstName": "Einstein",
       "lastName": "Bela",
       "fullName": "Einstien James Bela"
    }
  },
   "recipientKyc": {
     "subjectName": {
       "firstName": "John",
       "lastName": "Smith",
       "fullName": "John Dave Smith"
    }
  },
   "internationalTransferInformation": {
     "quoteId": "QT037fQXs3LGWXea4",
     "receivingCountry": "NG",
     "remittancePurpose": "Gift"
  }
}

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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 Type Optional Field Length
requestDate The creation date and time of the transaction as supplied by the client in YYYY-MM-DD HH:mm:ss format String No 19
amount Principle Transaction Amount with precision of 2 decimal places. String No 10,2
currency Currency of the principal transaction amount in ISO 4217 format. Eg. EUR String No 3
type The harmonized Transaction Type. "inttransfer" String No 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 Yes 0-20
requestingOrganisationTransactionReference Unique Transaction reference generated by the sending partner. String No 4-20
debitParty:
key msisdn String No 6
value Sender Mobile Number Eg. +91xxxxxxxxxx String No 10-18
creditParty:
Key msisdn String No -
Value Beneficiary Mobile Number Eg. +91xxxxxxxxxx String No 2-18
Key bankaccountno String No -
Value Beneficiary Bank Account Number Eg. 2365417895 String No 8-20
Key sortcode String No -
Value Beneficiary Bank Sort Code Eg. HDFC000XXXX String No 8-15
Key organisationid String No -
Value Beneficiary Bank organisation Id Eg. HDFC String No 4-18
senderKyc:
nationality Nationality of the customer in ISO Alpha-2 format. Eg. US String No 2
dateOfBirth Customer's Date of Birth in YYYY-MM-DD format String No 10
gender Customer's Gender. Enumeration = (m)ale, (f)emale, (u)nspecified String No 1
senderKyc:idDocument:
idType Customer's Id document type:
nationalidcard
drivinglicense
passport
String No 20
idNumber Customer's Id number.
For any other type, it should be Passport Number,Document number. Eg. M123456,123434567
String No 6-30
issueDate Customer's Id document issue date in YYYY-MM-DD format.
String No 10
expiryDate Customer's Id document expiry date in YYYY-MM-DD format.
String Yes 10
issuerCountry Country where the identification type was issued in ISO Alpha-2 format. String Yes 2
senderKyc:postalAddress:
addressLine1 First line of the address String Np 4-20
addressLine2 Second line of the address String Yes 4-20
addressLine3 Third line of the address String No 4-20
city City/Town of sender's address String No 4-20
stateProvince State of sender's address String No 4-20
postalCode Postal Code of sender's address String No 6-8
country Country in ISO Alpha-2 format String No 2
senderKyc:subjectName:
title Title of the Sender String Yes 0-6
firstName First name of the Sender String No 2-20
middleName Middle name of the Sender String Yes 0-50
lastName Last name of the Sender String No 2-20
fullName Full name of the Sender String No 2-50
recipientKyc:subjectName:
firstName First name of the recipient String No 2-20
lastName Last name of the recipient String No 2-20
fullName Full name of the recipient String No 2-50
internationalTransferInformation:
quoteId The specific quote associated with the quotation String No 17-20
receivingCountry Destination Country of international remittance in ISO Alpha 2 format. Eg. NG String No 2
remittancePurpose Reason for the transfer. Eg Gifts, Family expenses, etc String No 0-20

Create transaction response parameter list:

Parameter name Description 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

ViewATransaction


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

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

View Transaction Status to a Mobile Wallet

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

HTTP Request
GET /eig/gsma/transactions/TPKM000000056269 HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
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
Content-Length: length
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 Type Optional
transactionReference Unique reference for the transaction. This is returned in the response by Terrapay's system String No

View transaction response parameter list:

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

Ledger Balance


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

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

Get Balance of all ledgers.

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

HTTP Request
GET /eig/gsma/accounts/all/balance HTTP/1.1
Host: xxx.xxx.xxx.xxx
Content-Type: text/json; charset=utf-8
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

HTTP Response - Success
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: length
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
Content-Length: length
X-USERNAME: "partnerUserName"
X-PASSWORD: "partnerPassWord"
X-DATE: "2017-05-03 11:00:00"
X-ORIGINCOUNTRY:"originCountryCode"

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

                                                            

Response Codes & Messages



Response Code Response Message
1000 Invalid [propertyName]
1001 [propertyName] value should be between [minlength] to [maxlength]
1002 [propertyName] must be [length]
1003 Authentication failed. Username or Password is incorrect.
1004 Invalid parameters in the request
1005 Mandatory fields are missing
1006 Request SHA2 checksum mismatch
1007 Failure due to unknown reason
1010 Source country not allowed
1011 Destination country not allowed
1012 Source currency not allowed
1013 Destination currency not allowed
1014 Source country inactive
1015 Destination country inactive
1016 Failed to get destination partner
1017 Source partner validity fail
1018 Destination partner validity fail
1019 Source partner suspended
1020 Destination partner suspended
1021 Source partner inactive
1022 Destination partner inactive
1023 Corridor validity failed
1024 Corridor Suspended
1026 Source MSISDN not allowed.
1027 Source MSISDN Blacklisted.
1028 Destination MSISDN not allowed.
1029 Destination MSISDN Blacklisted.
1030 Corridor not exists
1031 Source currency inactive
1032 Destination currency inactive
1046 Invalid Transaction ID.
Response Code Response Message
2000 Quote Success
2001 Source amount is invalid
2002 Beneficiary MSISDN validation failed
2003 Failed to get Forex rate
Response Code Response Message
3000 Remit Success
3050 Remit Acknowledged, status PENDING
3001 Transaction request should be current date..
3002 Beneficiary MSISDN validation failed
3003 TerraPay transaction id is invalid
3004 Duplicate transaction Id
3005 Remit amount does not match quote amount
3006 Sender KYC details incomplete
3007 Beneficiary Validation failed
3008 Quote expired
3009 Failed to process quote request
3010 Mandatory KYC parameter check failed
3030 Possible duplicate transaction received within configured time.
3031 Connection timeout while connecting to destination partner
3032 Remit failed
3075 Sending Partner Min allowed amount check failed.
3076 Sending Partner Max allowed amount check failed.
3077 Receiving Partner Min allowed amount check failed.
3078 Receiving Partner Max allowed amount check failed.
3079 Sender Min allowed amount check failed.
3080 Sender Max allowed amount check failed.
3081 Receiver Min allowed amount check failed.
3082 Receiver Max allowed amount check failed.
3100 Credit Failed. Msisdn not found.
3101 Bank Credit Failed. Invalid Account.
3102 Bank Credit Failed. Bank Not Reachable.
3103 Bank credit failed. Account name mismatch.
3104 Bank credit failed. Transaction limit exceeded.
3105 Bank credit failed. Transaction not permitted.
3106 Bank credit failed. Unknown Error.
3107 Invalid Amount Limit.
3108 Invalid Digital Signature.
3109 Insufficient funds in the receiving partner account.
3110 Invalid beneficiary account
3111 Beneficiary aaccount not Registered
3113 Beneficiary account limit reached.
3132 Remit Failed - Max retry limit reached.
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
6000 Beneficiary Validation Success
6001 Corridor not alloweds
6002 Corridor inactive
6003 Beneficiary MSISDN blacklisted
6004 Beneficiary validation failed
6005 Beneficiary Registered but not KYCed
6006 Beneficiary Not Registered
6007 Beneficiary Suspended
6008 Beneficiary name does not match
6009 Beneficiary MSISDN validation failed
6010 Mandatory KYC parameter check failed
6011 Validation Failed. Beneficiary must register or upgrade KYC Level to receive transactions
6012 Beneficiary KYC Verification Pending
6013 Receiver Name Missing
6014 Customer Not Registered
6017 Beneficiary Account is locked
6101 Destination bank not configured
6102 Invalid Bank Account Number
6103 Destination bank not reachable
6104 Validation Failed at Destination Partner


About Us

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

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

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

For more information on TerraPay visit www.terrapay.com

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

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

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

Click here for more information on Mahindra Comviva.