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