REST API Specifications


Introduction

We created a complete and detailed description of the Platform API. Here you can find all parameter descriptions.


Hosts

  • Test:
  • Live:

Security / Authentication

All requests must be sent over SSL (Secure Socket Layer).

You need to generate an Authentication token to authenticate your request. Authentication parameters needs to be send in the header with each request. To generate authentication token please refer Auth token API.


Member ID and checksum can also be required in some cases. Please refer specific APIs for more details.


Authentication parameters need to be pass as POST parameters. You can find more details about these parameters in Authentication parameters.


Testing

For testing purpose you can use below card/account details:


Test Card Details

Brand Number CVV Expiry Date
VISA 4000000000000051 745 any future date
MASTER 5101082187256503
5101080000000009
123 any future date
AMEX 375510513169537
378282246310005
123 any future date


Test 3D Card Details

Brand Number CVV Expiry Date
VISA 4000000000000002 237 any future date


Test Bank Accounts (SEPA)

Country IBAN BIC
Germany (DE) DE09100100101234567893 PBNKDEFFXXX


Test Bank Accounts (ACH/CHK)

Country Account Number Routing Number Account Type
United States (US) 9876543210 011000028 PC/ PS/ CC


Basic Payment

This reference list lists all the standard flow parameters to be send in request.

Parameter Description Format Required
amount Amount of the transaction. The dot needs to add to separate the decimal. N13
[0-9]{1,10}\.[0-9]{2}
Yes
tmpl_amount Customized amount of customer, template amount can be same as transaction amount, Accept only [0-9] and ‘.’ (Single point) N11
[0-9]{1,8}\.[0-9]{2}
No
currency Currency of he transaction. A3
[a-zA-Z]{3}
Yes
tmpl_currency Currency of the customized amount to facilitate customer, template currency can be same as transaction currency, Accept only 3 character currency code in capital letters. AN3
[a-zA-Z0-9]{3}
No
paymentBrand Type of Card while placing the transaction.
For ex: VISA, MASTER
AN32
[a-zA-Z0-9] {1,32}
Yes
paymentMode Payment method for paying amount.
For ex: CC for Credit Cards
AN32
[a-zA-Z0-9] {1,32}
Yes
paymentType The payment type for the request. You can send a transaction requests with one of the following types:
  • PA, Preauthorization: A request made by the merchant to the gateway to authorize the availability of a required amount of funds for a specific credit card. An authorization verifies that a card is valid and has sufficient funds to complete this transaction. If approved, the authorized amount is held until it is completed, or an expiry time is reached.
  • DB, Debit: A transaction combining both, the Auth and Capture transactions. It instructs the gateway to perform both actions one after the other, query the bank for authorization and – upon approval – immediately capture the relevant transaction.
  • CP, Capture: Request to capture a previously-authorized transaction hence transferring the funds from customer’s bank account to merchant’s bank account. This transaction is always preceded by an auth transaction.
  • RV, Reversal: Requests to cancel previously authorized transaction. It returns the specified amount to the cardholder’s account. The amount being requested for reverse is less than or equal to the original authorized amount.
  • RF, Refund: Request to refund a previously settled transaction. However it is not possible to refund the same transaction more than once. It returns the specified amount (posts a credit) to the cardholder’s account. The amount being requested for refund is less than or equal to the original captured amount.
  • IN, Inquiry: Request to inquire the detail information of the previously placed transaction.
  • DL, Delete: To delete the registered registration ID.
A2
((PA|CP|DB|RF|RV|IN|DL))
Yes
orderDescription Description of the order. AN255 No
merchantTransactionId This reference number is provided by the merchant, should be unique for the transactions and is visible on the end customer’s statement. [.\\p[0-9a-zA-Z\\p{Space}\\-]{0,1024} Yes
merchantRedirectUrl Redirect url where the customer to be redirected after processing. Redirect URL provided in request will redirect customer on merchant's website. AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*)
Yes

notificationUrl This URL will receive the asynchronous notification where applicable.
This URL must be sent URL encoded.
AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*)
No

attemptThreeD On 3D secure merchant account, you can process Direct, 3D or Only3D type of transactions.
Direct - Synchronous transaction
3D - In this type if your card isn't 3D authenticated then it will be a synchronous transaction.
Only3D - Only 3D secure cards will get processed.
AN10
[Direct|3D|Only3D]
No



Authentication

Authentication data is required in all requests. You can find a set of valid credentials in the tutorials. But if you want to set up another credential for your terminal please contact us.

Parameter Description Format Required
authentication.memberId Merchant’s unique ID assigned by to authenticate a transaction request. N10
[0-9]
Yes
authentication.checksum Cryptographic hash generated by MD5 as follows.
All the processes has different combination of
parameters to generate hash (all values
separated by pipe). Kindly refer sample
given in tutorial for each case.
AN255
[a-zA-Z0-9]
Yes
authentication.terminalId Merchant’s terminal ID provided by . N4
[0-9]
No
authentication.sKey Merchant’s secure key which he uses to authenticate the transaction. AN32
[A-Za-z0-9]
No


Merchant

Merchant data is required in some requests. You can find a set of valid credentials in the tutorials. But if you want to set up another credential for your terminal please contact us.

Parameter Description Format Required
merchant.password Merchant's password which he uses to login in backoffice.
(Deprecated) Please use authentication.sKey instead of password
AN100
[A-Za-z0-9!@#$%^&*()]
No


Card Account

All the information about a credit or debit card account are hold by the card object

Parameter Description Format Required
card.number Customer’s card number. N19
((4[0-9]{12}([0-9]{3}))|(5[1-5][0-9]{14}))
Yes
card.expiryMonth Expiry month of the card. N2
([0-9])|(0[0-9])|(1[0-2])
Yes
card.expiryYear Expiry year of the card. N4
((200[0-9])|(201[0-9])|(202[0-9]))
Yes
card.cvv 3 or 4 digits number on card to verify card details. N4
[0-9]{3,4}
Yes


Bank Account

All important information about a bank account are hold by the bank account object and it is used for bank account based payments, e.g. bank transfers or direct debits. If you want to collect money from the customer’s bank account, you are in need of his approval.

Parameter Description Format Required
bankAccount.iban IBAN (International Bank Account Number) associated with the bank account. AN31
[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{11,27}
Yes
bankAccount.bic BIC (Bank Identifier Code (SWIFT)) number of the bank account holder. AN11
[a-zA-Z0-9]{8}|[a-zA-Z0-9]{11}
Yes
bankAccount.country Country code of the bank account holder. AN2
[a-zA-Z0-9]{2,1000}
No
bankAccount.mandate.id Unique ID of the mandate for bank account. AN256
[a-zA-Z]{0,256}
Conditional
bankAccount.accountNumber The merchant's bank account number. Maximum length is 17 characters. AN17
[0-9]{0,17}
Conditional
bankAccount.accountType The merchant's Bank Account Type.
(‘PC’- Personal Checking, ‘PS’- Personal Savings, ‘CC’ – Commercial Checking).
A2
[a-zA-Z]{0,2}
Conditional
bankAccount.routingNumber Merchant's 9 digit bank routing number. N9
[0-9]{9}
Conditional


Customer

All the information about the customer like his name, contact details and identification documents are hold by the customer object.

Parameter Description Format Required
customer.givenName First name of the customer. AN
[a-zA-Z0-9\\p{Space}\\,.:'"-=+)({}[]]+
No
customer.surname Last name or surname of the customer. AN
[a-zA-Z0-9\\p{Space}\\,.:'"-=+)({}[]]+
No
customer.birthDate Birth date of the customer in the format YYYYMMDD. AN10
{19|20)([0-9]{2})(0[1-9]|1[0-2])(0[1-9]|1[0-9]|2[0-9]|3[0-1]}
No
customer.phone Phone number of the customer. AN25
[a-zA-Z0-9\+-.]{6,25}
No
customer.telnocc Country code of the customer. N4
[0-9]{1,4}
No
customer.ip IP address of the customer. AN255
(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)
No
customer.email Email address of the customer. AN50
[A-Za-z0-9._%'-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}
Conditional
customer.bankId Customer ID in bank's system. AN20
[a-zA-Z0-9]{1,20}
Conditional
customer.customerId Customer ID in merchant’s system. AN15
[a-zA-Z0-9]{1,15}
No


3D Secure

3D secure object is used for authenticating data generated by the 3D secure MPI. Object can be used for authentication when external MPI is being used.

If 3D secure object is used, payment gateway just pass the details to acquirer.

Parameter Description Format Required
threeDSecure.eci ECI for threeD Secure request. N2
[0-9]{2}
No
threeDSecure.verificationId threeD Secure CAVV/AVV in Base64 encoded. AN50
[a-zA-Z]{50}
No
threeDSecure.xid threeD Secure xid in Base64 encoded AN100
[a-zA-Z]{100}
No


Shipping Address

The details about the recipient and location of an order are held by the shipping address object.

Parameter Description Format Required
shipping.street1 Building name, and/ or street name of the customer's shipping address. AN1000
[a-zA-Z0-9\\p{Space}\\,]+
Conditional
shipping.city City of the customer's shipping address. AN50
[a-zA-Z0-9\\\\#&\\p{Space}\\p{L}\\p{M}\\-;.,~`/%$#@ ]{0,1000}
Conditional
shipping.state State or region of the customer's shipping address. AN50
[\\ra-zA-Z0-9\\\\!@#$*%^&{}\\[\\]()_+\\p{L}\\p{M}\\-=,.~'` ]{0,1000}
Conditional
shipping.postcode Postal code/ Zip code of the customer's shipping address. AN10
[A-Za-z0-9]{1,10}
Conditional
shipping.country Country of the shipping address. AN3
[a-zA-Z0-9]{2,3}
Conditional


Inquiry

There are two ways to find transaction details on the system. You need to provide idType to inquire the transaction. Please see the BackOffice for further information.

Parameter Description Format Required
idType It specifies the type of request id. PID is PaymentID and MID is merchantTransactionId. AN3
(MID|PID)
No


Payout

To place the payout transaction you need to provide either paymentId or custAccount. Please see the Payout for further information.

Either paymentId of previously placed successful transaction or need to send fresh transaction request with payment type PO.

Parameter Description Format Required
paymentId Transaction ID of previously placed successful transaction. N10
[0-9]
Conditional
payoutType Type of the payout, type can be approval or cancel A10
(approval|cancel)
Conditional
notificationUrl This URL will receive the asynchronous notification where applicable.
This URL must be sent URL encoded.
AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*)
Conditional



Tokenization

There are two ways to store customer’s data on the system. Please see the Tokenization Guide for further information.

Parameter Description Format Required
createRegistration For the createRegistration when value is TRUE, system will generate unique registration ID which has stored card details. A4
true
No


Recurring

As described in the Recurring Guide, all you have to do for sending recurring transactions is to flag the transaction with the following parameter:

Parameter Description Format Required
recurringType It is used to indicate the recurring type of the transaction.
  • INITIAL: This is the initial(first) Pre-Auth or Debit transaction with the value recurringType = INITIAL.
  • REPEATED: The transaction is a subsequent transaction. From initial recurring transaction card details are fetched for repeated recurring transaction.
A10
INITIAL|REPEATED
No
paymentId The payment ID of the previous successful transaction for which the customer wants to place a repeated recurring transaction. N10 Conditional
registrationId This ID is used to fetch card details of the customer. AN32 Conditional


Asynchronous Payments

Parameter Description Format Required
notificationUrl This URL will receive the asynchronous notification where applicable.
This URL must be sent URL encoded.
AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*)
No

Response Parameters for Asynchronous Payment

Parameter Description Format Required
redirect.url With this URL shopper gets redirected for the further transaction. AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*)
Conditional
redirect.parameters[n].name List of parameter names for the redirect.url. The corresponding parameter value is the same parameter number ending with .value like described in the line below. The actual return format is JSON as shown in the example snippet below. AN255
[a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+
Conditional
redirect.parameters[n].value The parameter values corresponding to the names as described above. AN255
[a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+
Conditional


Response Parameters

Parameter Description Format Required
paymentId Unique transactionId sent by . N10
[0-9]
Yes
id (/registrations) Identifier of the transaction request that can be used to reference the registration later. You get this either as the field id of a registration's response or as the field registrationId of a payment's response (if the request contained createRegistration=TRUE). AN32
[a-zA-Z0-9]{32}
Yes
paymentBrand Type of Card while placing the transaction.
For ex: VISA, MASTER
A50
[A-Za-z]
Conditional
paymentType The payment type for the request. A2
[A-Za-z]
Conditional
paymentMode Payment method for paying amount.
For ex: CC for Credit Cards
A50
[A-Za-z]
Conditional
amount Amount of the transaction. N13
[0-9]{1,10}\.[0-9]{2}
Conditional
currency Currency of the transaction. A3
[a-zA-Z\\p{Space}\\,]+
Conditional
descriptor Display name of the merchant. AN127
[a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+
Conditional
transactionStatus Status of the transaction processed. Possible values are,
‘Y’ – Successfully processed
‘N’ – Failed
‘P’ – Pending
‘3D’ – Pending for 3D authentication
‘C’ – Cancelled
AN2
[Y|N|P|3D|C]
Yes
remark Transaction remark from respective gateway. AN255
[a-zA-Z0-9]
Yes
status Status of the transaction. You can refer status descriptions for more detailed information. AN255
[a-zA-Z0-9]
Yes
result.code The unique response code for successful or failed transaction. See the Response codes for more detailed information. AN11
[0-9\.]{2,11}
Yes
result.description Response description of the response code. AN255
[a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+
Yes
card.bin First six digits of the card number. N6
[0-9]{6}
No
card.last4Digits Last four digits of the card number. N4
[0-9]{4}
No
card.holder Name of the customer on card. AN255
[a-zA-Z0-9]
No
card.expiryMonth Expiry month on card. N2
[0-9]
No
card.expiryYear Expiry year on card. N4
[0-9]
No
merchant.bankAccount.holder Full name of the user. AN128
[a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+{4,128}
Yes
merchant.bankAccount.number Account number of the bank account. AN64
[a-zA-Z0-9]{3,64}
Conditional
merchant.bankAccount.bic The BIC (Bank Identifier Code) of the merchant's bank account. AN11
[a-zA-Z0-9]{8}|[a-zA-Z0-9]{11}
Conditional
merchant.bankAccount.country The country code of the merchant's bank account. AN2
[a-zA-Z0-9]{2,1000}
Conditional
merchantTransactionId Unique ID sent at the time of transaction. AN1024
[.\\p[0-9a-zA-Z\\p{Space}\\-]{0,1024}
Conditional
timestamp Shows at what time the transaction has been placed. date
yyyy-MM-dd hh:mm:ss
Yes
customer.email Email address of the customer. AN50
[A-Za-z0-9._%'-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}
Conditional
customer.bankId Customer ID in bank's system. AN20
[A-Za-z0-9]
Conditional
customer.id Customer ID in merchant’s system. AN20
[A-Za-z0-9]
Conditional
eci eci is the two or three digit code that is returned by the credit card processing networks and issuing banks.For VISA eci code is (05,06,07)and for MasterCard eci code is(01,02). N3
[0-9]
Optional
firstName First name of the cardholder. AN20
[A-Za-z0-9]
Optional
lastName Last name of the cardholder. AN20
[A-Za-z0-9]
Optional
tmpl_amount Customized amount of customer, template amount can be same as transaction amount. N13
[0-9]{1,9}\.[0-9]{2}
No
tmpl_currency Currency of the customized amount to facilitate customer, template currency can be same as transaction currency, Accept only 3 character currency code in capital letters. A3
[a-zA-Z]{3}
No
Other The response can also contain each of the resources listed above, such as customer and shipping address. n/a Conditional


ECI values(Electronic Commerce Indicator) For VISA CARD

ECI value Description
05 Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful
06 Either cardholder or card issuing bank is not 3D enrolled. 3D card authentication is unsuccessful,
in sample situations as:
1. 3D cardholder not enrolled
2. Card issuing bank is not 3D Secure ready
07 Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction


ECI values(Electronic Commerce Indicator) For MASTER CARD

ECI value Description
00 Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction
01 Either cardholder or card issuing bank is not 3D enrolled. 3D card authentication is unsuccessful,
in sample situations as:
1. 3D Cardholder not enrolled
2. Card issuing bank is not 3D Secure ready
02 Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful
Copyright © . All Rights Reserved