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).

The memberId and checksum are in need to authenticate every request against a particular terminal. And the POST parameters are used to send the authentication data. You need to generate an authentication token to authenticate your request. This token has to be sent with the header every time you POST the request. You can find more details about that in the Authentication Parameters.


Testing

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


Credit Card Test Details

Brand Number CVV Expiry Date
VISA 4111111111111111
4176661000001056
123
001
any future date
MASTER 5549110920049586
5423110020223322
608
001
any future date
AMEX 370000000000002
376000000000006
000
608
any future date


Test Bank Accounts (SEPA)

Country IBAN BIC
Germany (DE) DE23100000001234567890 MARKDEF1100


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 Transaction request amount. Decimal format needs to be followed N13
[0-9]{1,10}\.[0-9]{2}
Yes
currency Transaction request currency A3
[a-zA-Z]{3}
Yes
paymentBrand It specifies the brand type of payment for the request AN32
[a-zA-Z0-9] {1,32}
Yes
paymentMode It specifies the mode of payment for the request 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|CD|RF|RV|IN|DL))
Yes
orderDescription It takes description of the order placed by customer AN255 Yes
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 This URL will receive the result of an asynchronous payment.
It must be sent URL encoded.
AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*)
Yes



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


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 code 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 Telephonic country code of the customer N4
[0-9]{1,4}
No
customer.email Email address of the customer AN
[A-Za-z0-9._%'-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,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


Shipping Address

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

Parameter Description Format Required
shipping.street 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 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


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 value will always be TRUE. If the value is true then system will generate a unique token from which system can get card details of the customer. 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 = TRUE
  • 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
id (/payments) It is necessary to identify the payment request later. The value appears in the ID field of a payment's response. Later you can use this value as payment ID or for sending reference tracking requests 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 Payment-type of the request AN32
[A-Za-z]*
Conditional
paymentMode Card-type of the request AN32
[A-Za-z]*
Conditional
amount Amount of the request N13
[0-9]{1,10}\.[0-9]{2}
Conditional
currency Currency of the request A3
[a-zA-Z\\p{Space}\\,]+
Conditional
descriptor Unique descriptor of the request AN127
[a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+
Conditional
result.code The unique response code that indicates the response status of the request. 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}\\,]+
No
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
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) number 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 reference number provided by merchant AN1024
[.\\p[0-9a-zA-Z\\p{Space}\\-]{0,1024}
Conditional
Other The response can also contain each of the resources listed above, such as customer and shipping address n/a Conditional
timestamp Shows at what time the transaction has been placed date
yyyy-MM-dd hh:mm:ss
Yes