- Get Started
- Guides
- Integrations
- References
- API Reference
- Basic Payment
- Forex
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Merchant
- Corporate
- Recipient
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Job
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- API Reference
- Support
![Home](https://paynt-email-signature-images.s3.eu-west-1.amazonaws.com/Paynt-logotype_167x60px-30.png)
API Reference
Introduction
This reference section provides you with a complete and in-depth description of the Payment Platform API.
Hosts
- Test: https://eu-test.oppwa.com/
- Live: https://eu-prod.oppwa.com/
Security / Authentication
All requests must be sent over SSL
All requests are authenticated against an Authorization Bearer header with an access token. All the other data parameters are sent as body parameters, see Authentication Parameters for more information.
Throttling
Throttling is the process of limiting the number of requests submitted to a given operation in a given amount of time. Throttling protects the web service from being overwhelmed with requests and ensures providing a healthy web service.
Following throttling values has been configured:
Live system
Test system
Requests which will be affected by throttling, will be rejected with following return code:
{ "buildNumber": "b297e8ec4aa0888454578e292c67546d4c6a5c28@2018-08-30 06:31:46 +****", "id": "8ac9a4a8658afc790165a3f0e436198d", "ndc": "8acda4c9635ea2d90163636f0a462510_ebb07f3e26e942908d6eeed03a813237", "result": { "code": "800.120.100", "description": "Too many requests. Please try again later." }, "timestamp": "2018-09-04 09:42:33+0000" }
Versioning
The API version is indicated in the request URL e.g. /v1/payments indicates version 1.
All changes made to the API are backwards compatible, hence any major features that are released, that would otherwise break existing implementations, will be released using a new version.
Encoding
Our system expects data to be sent encoded in UTF-8.
Using this Content-Type header can help:
application/x-www-form-urlencoded; charset=UTF-8
HTTP Status Codes
For each request you send to our API the HTTP status code
of the response will already tell you the basic result.
200 - successful request
307 - temporary redirect
400 - bad request. This might either point to e.g. invalid parameters or values sent. It's also returned if the payment failed e.g. because the acquirer declined.
401 - invalid authorization header provided
403 - invalid access token provided
404 - requested resource or endpoint is not found. I.e. endpoint/url doesn't exist. This can also be caused by typos like POST /v1/paymnets instead of payments or wrong IDs like GET /v1/payments/{id} where no payment with {id} exists.
For payments you'll want more fine grained information to find out why a payment failed. You're getting this information in the result codes.
HTTP Response Body
HTTP response body is following JSON format. Please process the HTTP response properly and please expect new fields being added to the JSON structure at any time in the future. See an example of what OPP response message could look like:
HTTP 200 { "id":"8ac7a4a289d210fc0189d5b4e9572cc8", "paymentType":"DB", "paymentBrand":"VISA", "amount":"92.00", "currency":"EUR", "descriptor":"7766.2840.5126 OPP_Channel ", "result":{ "code":"000.100.110", "description":"Request successfully processed in 'Merchant in Integrator Test Mode'" }, "resultDetails":{ "ExtendedDescription":"Authorized", "clearingInstituteName":"Your Clearing Institute Name", "ConnectorTxID1":"00000000776628405126", "ConnectorTxID3":"0170|085", "ConnectorTxID2":"012416", "AcquirerResponse":"0000" }, "card":{ "bin":"420000", "last4Digits":"0000", "holder":"Jane Jones", "expiryMonth":"05", "expiryYear":"2034" }, "risk":{ "score":"100" }, "buildNumber":"5ce30a257f96b238fa8ecc669ffdc2a77040ba35@2023-08-08 07:36:04 +0000", "timestamp":"2023-08-08 15:12:30.752+0000", "ndc":"8a8294174b7ecb28014b9699220015ca_83281e556b1e4216bef5c3bc1f63c45c" }
Testing
It is important to note that we have two test modes available to cause requests to be sent to our simulator or to the acquirers/APM/partner own test platform, as required:
testMode=EXTERNAL
causes test transactions to be forwarded to the processor's test system for 'end-to-end' testingtestMode=INTERNAL
causes transactions to be sent to our simulators.
If no testMode parameter is sent, testMode=INTERNAL
is the default behaviour
Credit Card Test Accounts
Brand | Number | CVV | Expiry Date |
---|---|---|---|
VISA | 4200000000000000 (no 3D) 4711100000000000 (3D enrolled) |
any 3 digits | any date after today |
MASTER | 5454545454545454 (no 3D) 5212345678901234 (3D enrolled) |
any 3 digits | any date after today |
AMEX | 377777777777770 (no 3D) 375987000000005 (3D enrolled) |
any 4 digits | any date after today |
Test Bank Accounts (SEPA)
Country | IBAN | BIC |
---|---|---|
Austria (AT) | AT152011128161647502 | GIBAATWWXXX |
Germany (DE) | DE23100000001234567890 | MARKDEF1100 |
Spain (ES) | ES9121000418450200051332 | CAIXESBBXXX |
This reference lists all the Payment Platform parameters, grouped by their data structures.
Basic Payment
Parameter | Description | Format | Required |
---|---|---|---|
amount | Indicates the amount of the payment request. The dot is used as decimal separator. The amount is the only amount value which is processing relevant. All other amount declarations like taxAmount or shipping.cost are already included. | N10.N2 [0-9]{1,10}(\.[0-9]{2})? |
Required |
taxAmount | Indicates the tax amount of the payment request. The dot is used as decimal separator. | N10.N2 [0-9]{1,10}(\.[0-9]{2})? |
Conditional |
discountAmount | L3 Card data invoice level discount amount | N10.N2 [0-9]{1,10}(\.[0-9]{2})? |
Optional |
currency | The currency code of the payment request's amount (ISO 4217). | A3 [A-Z]{3} |
Required |
paymentBrand | The brand specifies the method of payment for the request. This is optional if you want to use brand detection for credit cards, if not then it is mandatory. | AN32 [a-zA-Z0-9_] {1,32} |
Conditional |
paymentType | The payment type for the request. You can send payment requests with one of the following types:
|
A2 | Required |
overridePaymentType[brand] | The payment type can be overriden for specific brands, for example: overridePaymentType[BOLETO]=PA overridePaymentType[KLARNA_INVOICE]=PA In such cases, the default payment type will be the one defined in paymentType parameter and every brand defined in overridePaymentType will have its own payment type. This parameter is only accepted during the checkout creation. |
brand: AN32 [a-zA-Z0-9_]{1,32} value: A2 |
Optional |
descriptor | Can be used to populate all or part of the Merchant Name descriptor, which often appears on the first line of the shopper's statement. The full use of this field depends on the Merchant Account configuration. NOTE: merchant.name can override any data sent in this field. |
AN127 [\s\S]{1,127} |
Optional |
merchantTransactionId | Merchant-provided reference number, should be unique for your transactions. Some receivers require this ID. This identifier is often used for reconciliation. | AN255 [\s\S]{8,255} |
Conditional |
merchantInvoiceId | Merchant-provided invoice number, should be unique for your transactions. This identifier is not sent onwards. | AN255 [\s\S]{8,255} |
Optional |
merchantMemo | Merchant-provided additional information. The information provided is not transaction processing relevant. It will appear in reporting only. | AN255 [\s\S]{8,255} |
Optional |
transactionCategory | The category of the transaction, possible values are:
|
AN32 [a-zA-Z0-9]{0,32} |
Optional |
sequence | Additional field sent by Merchant to indicate last transaction for CP, RV, RF etc.
sequence=FINAL indicates this is the last transaction. |
AN |
Optional |
numberOfCaptures | Sets the maximum number of possible partial Captures. | N2 [1-9]|[1-8][0-9]|9[0-8] |
Optional |
promotionCode | Discount code applied at the Order level. There will be 1 Promotion Code per order. | AN15 [A-Za-z0-9]{0,15} |
Optional |
locale | Sets the language/country. Examples : "de-AT", "en-US". etc Note: Check the requirements of the connector you are integrating in your shop to understand which language/country that connector supports. |
AN10 [\s\S]{1,10} |
Optional |
Forex
Parameter | Description | Format | Required |
---|---|---|---|
forex.amount | The amount of the request which could be used when there is a process of changing one currency into another during the transaction. | N10.N2 [0-9]{1,10}(\.[0-9]{2})? |
Conditional |
forex.currency | ISO 4217 alphabetic currency code which could be used when there is a process of changing one currency into another during the transaction. (ISO 4217). | A3 [A-Z]{3} |
Conditional |
Authentication
To make REST API calls, include the access token in the Authorization header with the Bearer authentication scheme.
Parameter / Header | Description | Format | Required |
---|---|---|---|
entityId | The entity required to authorize the request. This should be the channel entity identifier. In case channel dispatching is activated then it should be the merchant entity identifier. | AN32 [a-f0-9]{32} |
Conditional |
Authorization Bearer <access-token> | Authorization header with Bearer authentication scheme. Access token can be taken from the backend UI under Administration > Account data > Merchant / Channel Info only if you have specific administration rights. | Header | Required |
Card Account
The card data structure holds all information regarding a credit or debit card account.
Parameter | Description | Format | Required |
---|---|---|---|
card.holder | Holder of the credit card account | A128 {3,128} |
Optional |
card.number | The PAN or account number of the card. | N32 [0-9]{8,32} |
Required |
card.expiryMonth | The expiry month of the card. | N2 (0[1-9]|1[0-2]) |
Required |
card.expiryYear | The expiry year of the card. | N4 (19|20)([0-9]{2}) |
Required |
card.cvv | The card security code or CVV | N4 [0-9]{3,4} |
Conditional |
Apple Pay
There are two possible APIs for Apple Pay:
Apple Pay with encrypted payment token
You can send the encrypted payment token as-is. We will do the decryption and process the transaction.
Parameter | Description | Format | Required |
---|---|---|---|
applePay.paymentToken | The encrypted payment token created by Apple | Defined by Apple | Required |
Apple Pay with decrypted card information
You can do the decryption by yourself and send us the decrypted card information with the usual card API: card.number, card.expiryMonth, card.expiryYear, threeDSecure.verificationId, threeDSecure.eci, and the following parameter:
Parameter | Description | Format | Required |
---|---|---|---|
applePay.source | Indicates the source of Apple Pay | web|app | Required |
Google Pay
There are two possible APIs for Google Pay:
Google Pay with encrypted payment token
You can send the encrypted payment token as-is. We will do the decryption and process the transaction.
Parameter | Description | Format | Required |
---|---|---|---|
googlePay.paymentToken | The encrypted payment token created by Google | Defined by Google | Required |
Google Pay with decrypted card information
You can do the decryption by yourself and send us the decrypted card information with the usual card API: card.number, card.expiryMonth, card.expiryYear, threeDSecure.verificationId, threeDSecure.eci, and the following parameter:
Parameter | Description | Format | Required |
---|---|---|---|
googlePay.source | Indicates the source of Google Pay | web|app | Required |
Virtual Account
The virtual account data structure is used to send account-based payments, e.g. PAYPAL.
Parameter | Description | Format | Required |
---|---|---|---|
virtualAccount.accountId | The identifier of the shopper's virtual account. | AN100 [\s\S]{1,100} |
Required |
Bank Account
The bank account data structure holds all the information that specifies a bank account. This is used for bank-account based payments, e.g. direct debits, SEPA and bank transfers. Collecting money from the shopper's bank account generally requires his approval. SEPA specific parameters - bankAccount.mandate.id, bankAccount.mandate.dateOfSignature,transactionDueDate are not used in the risk checks.
Parameter | Description | Format | Required |
---|---|---|---|
bankAccount.holder | Holder of the bank account | AN128 {4,128} |
Required |
bankAccount.bankName | The name of the bank which holds the account. | AN255 [\s\S]{1,255} |
Conditional |
bankAccount.number | The account number of the bank account. Either the number or the iban are required. | AN64 [a-zA-Z0-9]{3,64} |
Conditional |
bankAccount.iban | The IBAN (International Bank Account Number) associated with the bank account. Either the number or the iban are required. | AN31 [a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{11,27} |
Conditional |
bankAccount.bankCode | The code associated with the bank account. Either the bankCode or the bic are required. | AN12 [a-zA-Z0-9]{1,12} |
Conditional |
bankAccount.bic | The BIC (Bank Identifier Code (SWIFT)) number of the bank account. Either the bankCode or the bic are required. | AN11 [a-zA-Z0-9]{8}|[a-zA-Z0-9]{11} |
Conditional |
bankAccount.country | The country code of the bank account (ISO 3166-1). | AN2 [a-zA-Z]{2} |
Conditional |
bankAccount.mandate.id | The id of the mandate for direct debit. | AN256 [a-zA-Z\-]{0,256} |
Conditional |
bankAccount.mandate.dateOfSignature | The date the direct debit mandate was signed. | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Conditional |
transactionDueDate | The due date of the transaction of the direct debit. | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Conditional |
Token Account
The token account data structure is used to send token-based payments towards the acquirer.
Parameter | Description | Format | Required |
---|---|---|---|
tokenAccount.number | The encrypted payment token created by external provider | N19 [0-9]{12,19} |
Required |
tokenAccount.type | The type of the token account. Possible values:
|
EXTERNAL| NETWORK |
Required |
tokenAccount.expiryMonth | The expiry month of the token | N2 (0[1-9]|1[0-2]) |
Optional |
tokenAccount.expiryYear | The expiry year of the token | N4 (19|20)([0-9]{2}) |
Optional |
tokenAccount.cryptogram | Dynamic data generated using EMV-based cryptography to secure the transaction. Must be base64 encoded. | AN32 [\s\S]{28,32} |
Conditional |
tokenAccount.dtvc | Dynamic token verification code (dynamic one time CVC2 generated for a token) | N4 [0-9]{3,4} |
Conditional |
Customer
The customer data structure holds information about the customer/shopper such as their name, identification documents and contact details. The customer fields serve mixed purposes: On the one hand they are just for you to store information on your customers, but on the other hand they are also used and sometimes required for risk management and payment providers that require ID/mandate information. These use cases are noted in the parameters' descriptions.
Parameter | Description | Format | Required |
---|---|---|---|
customer.merchantCustomerId | An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system. | AN255 [\s\S]{1,255} |
Optional |
customer.givenName | The first name or given name of the customer. Required if you send in any other customer parameters, also required for some risk checks and payment providers. Max 50 characters | AN50 [\s\S] |
Conditional |
customer.middleName | The middle name of the customer. Max 50 characters | AN50 [\s\S]{2,50} |
Optional |
customer.surname | The last name or surname of the customer. Required if you send in any other customer parameters, also required for some risk checks and payment providers. Max 50 characters | AN50 [\s\S] |
Conditional |
customer.sex | Sex of the shopper, 'M' for male or 'F' for female | A1 M|F |
Optional |
customer.birthDate | The birth day of the customer in the format yyyy-MM-dd, e.g. 1970-02-17 | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Optional |
customer.phone | The customer's phone number. Required for some risk checks. | AN25 [+0-9][0-9 \.()/-]{0,25} |
Optional |
customer.mobile | The customer's mobile number. Required for some risk checks. | AN25 [+0-9][0-9 \.()/-]{0,25} |
Optional |
customer.workPhone | The customer's phone number. Required for some risk checks. | AN25 [\s\S]{1,25} |
Optional |
customer.email | The customer's email address. Required for some risk checks and transmission of direct debit mandates. | AN128 [\s\S]{6,128} |
Optional |
customer.companyName | The customer's company name. | AN60 [\s\S]{1,60} |
Optional |
customer.identificationDocType | The type of identification document for the customer. Can be one of these three values: IDCARD, PASSPORT, TAXSTATEMENT. If this parameter is sent then customer.identificationDocId must be also sent. It is also mandatory for certain payment types (e.g. Boleto). |
A12 [\s\S] |
Conditional |
customer.identificationDocId | The identifier of the identification document for the customer. If this parameter is sent then customer.identificationDocType must also be sent. It is also mandatory for certain payment types (e.g. Boleto). |
AN64 [\s\S]{8,64} |
Conditional |
customer.ip | The customer's IP address. | AN255 [\s\S]{1,255} |
Optional |
customer.merchantReference | Defines the payer account ID or some other form of reference information which will be provided to the payee | AN255 [\s\S] |
Optional |
customer.salutation | Valid options are: MR, MRS, MS, MX | A3 [\s\S] |
Optional |
customer.language | Defines the language of the customer. For example - NO, DE, etc. | [A-Z] {2} |
Optional |
customer.category | Defines whether payer is an individual customer or a company. Valid options are: INDIVIDUAL, COMPANY |
A10 [\s\S] |
Optional |
customer.browserFingerprint.id | The reference to the fingerprint of the shopper's browser, in most cases provided by some JavaScript library. | [\s\S]{1,255} | Optional |
customer.browserFingerprint.value | The actual fingerprint value of the shopper's browser | [\s\S]{1,4096} | Optional |
customer.browser.acceptHeader | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. Mandatory for 3D Secure v2. |
[\s\S]{1,2048} | Conditional |
customer.browser.language | Value representing the browser language as defined in IETF BCP47.
Returned from navigator.language property. Mandatory for 3D Secure v2. |
[\s\S]{1,8} | Conditional |
customer.browser.screenHeight | Total height of the Cardholder’s screen in pixels.
Value is returned from the screen.height property. Mandatory for 3D Secure v2. |
[\s\S]{1,6} | Conditional |
customer.browser.screenWidth | Total width of the cardholder’s screen in pixels.
Value is returned from the screen.width property. Mandatory for 3D Secure v2. |
[\s\S]{1,6} | Conditional |
customer.browser.timezone | Time-zone offset in minutes between UTC and the Cardholder browser local time.
Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead Mandatory for 3D Secure v2. |
[\s\S]{1,5} | Conditional |
customer.browser.userAgent | Exact content of the HTTP user-agent header. Mandatory for 3D Secure v2. |
[\s\S]{1,2048} | Conditional |
customer.browser.javaEnabled | Boolean that represents the ability of the cardholder browser to execute Java.
Value is returned from the navigator.javaEnabled property. Mandatory for 3D Secure v2. |
true/false | Conditional |
customer.browser.screenColorDepth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. | N2 [0-9]{1,2} | Optional |
customer.browser.challengeWindow | Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window. | N1 | Optional |
customer.browser.deviceId | Value representing the customer browser device id. | AN32 [\s\S]{1,32} |
Optional |
customer.app.deviceId | Value representing the customer mobile device id. | AN40 [\s\S]{1,40} |
Optional |
customer.status | A status of the customer. Currently two options- NEW, EXISTING. | A9 [\s\S]{1,255} |
Optional |
Shipping customer
The shipping customer has the same fields than the billing customer, just as part of the shipping entity. That way you can ship to an entirely different customer.
Parameter | Description | Format | Required |
---|---|---|---|
shipping.customer.* | All the fields that are available under customer except shipping.customer.browserFingerprint.*, shipping.customer.browser.deviceId and shipping.customer.app.deviceId | Same as for customer fields | Optional |
Billing Address
The billing address holds the address of the customer. Information sent in the billing address data structure can optionally be used for risk checks such as AVS for card processing.
Parameter | Description | Format | Required |
---|---|---|---|
billing.street1 | The door number, floor, building number, building name, and/or street name of the billing address Mandatory for 3D Secure v2. |
AN100 [\s\S]{1,100} |
Conditional |
billing.street2 | The adjoining road or locality (if required) of the billing address The combination of billing.street1 and billing.street2 can't contain numbers only, it should also include characters. |
AN100 [\s\S]{1,100} |
Conditional |
billing.houseNumber1 | Primary house number (door number or building number) of the billing address. If present, then billing.street1 is assumed to contain only the name of the street. Also, billing.street2 will be ignored. | AN100 [\s\S]{1,100} |
Optional |
billing.houseNumber2 | Secondary house number (floor, building name) of the billing address. Used when more addresses are bundled to a same primary house number. If present, billing.houseNumber1 is also mandatory. | AN100 [\s\S]{1,100} |
Optional |
billing.city | The town, district or city of the billing address Mandatory for 3D Secure v2. |
AN48 [\s\S]{1,48} |
Conditional |
billing.state | The county, state or region of the billing address | AN50 [a-zA-Z0-9\.]{1,50} |
Conditional |
billing.postcode | The postal code or zip code of the billing address Mandatory for 3D Secure v2. |
AN16 [A-Za-z0-9]{1,16} |
Conditional |
billing.country | The country of the billing address (ISO 3166-1) Mandatory for 3D Secure v2. |
A2 [A-Z]{2} |
Conditional |
billing.normalized | The normalized shipping address. | AN255 [\s\S]{1,255} |
Optional |
billing.validationStatus | Indicates whether a address got validated and normalized address got confirmed by the consumer | AN255 [\s\S]{1,255} |
Optional |
Merchant Billing Address
The merchant billing address has the same fields as billing address with additional parameters, just as part of the merchant entity. That way you can bill from an entirely different merchant location.
Parameter | Description | Format | Required |
---|---|---|---|
merchant.billing.* | All the fields that are available under billing address | Same as for billing address fields | Optional |
merchant.billing.givenName | The first name or given name of the merchant/acceptor | AN [\s\S] |
Optional |
merchant.billing.surname | The last name or surname of the merchant/acceptor | AN [\s\S] |
Optional |
merchant.billing.middleName | The middle name of the merchant/acceptor | AN [\s\S] |
Optional |
merchant.billing.companyName | The merchant's company name | AN60 [\s\S]{1,60} |
Optional |
merchant.billing.phone | The merchant's phone number | AN25 [\s\S]{1,25} |
Optional |
merchant.billing.workPhone | The merchant's work phone number | AN25 [\s\S]{1,25} |
Optional |
merchant.billing.mobile | The merchant's mobile number | AN25 [+0-9][0-9 \.()/-]{5,25} |
Optional |
merchant.billing.email | The merchant's email address | AN128 [\s\S]{6,128} |
Optional |
Shipping Address
The shipping address holds the location and recipient of ordered goods. This can be used for risk processing or logistics.
Parameter | Description | Format | Required |
---|---|---|---|
shipping.street1 | The door number, floor, building number, building name, and/or street name of the shipping address | AN100 [\s\S]{1,100} |
Conditional |
shipping.street2 | The adjoining road or locality (if required) of the shipping address | AN100 [\s\S]{1,100} |
Conditional |
shipping.houseNumber1 | Primary house number (door number or building number) of the shipping address. If present, then shipping.street1 is assumed to contain only the name of the street. Also, shipping.street2 will be ignored. | AN100 [\s\S]{1,100} |
Optional |
shipping.houseNumber2 | Secondary house number of the shipping address (floor, building name). Used when more addresses are bundled to a same primary house number. If present, shipping.houseNumber1 is also mandatory. | AN100 [\s\S]{1,100} |
Optional |
shipping.city | The town, district or city of the shipping address | AN80 [a-zA-Z]{1,80} |
Conditional |
shipping.state | The county, state or region of the shipping address | AN50 [a-zA-Z0-9\.]{1,50} |
Conditional |
shipping.postcode | The postal code or zip code of the shipping address | AN16 [A-Za-z0-9]{1,16} |
Conditional |
shipping.country | The country of the shipping address (ISO 3166-1) | A2 [A-Za-z]{2} |
Conditional |
shipping.method | Method of the shipping. One of the options: CARRIER_DESIGNATED_BY_CUSTOMER, ELECTRONIC_DELIVERY, EXPEDITED, GROUND, INTERNATIONAL, LOWEST_COST, MILITARY, NEXT_DAY_OVERNIGHT, OTHER, POINT_PICKUP, PUDO, SAME_DAY_SERVICE, STORE_PICKUP, THREE_DAY_SERVICE, TWO_DAY_SERVICE | AN30 [A-Z_]{5,30} |
Conditional |
shipping.cost | The total amount of the shipping costs. | N13 [0-9]{1,10}\.[0-9]{2} |
Conditional |
shipping.comment | A comment for the shipping | AN160 [\s\S]{1,160} |
Conditional |
shipping.expectedDate | The expected delivery date | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Optional |
shipping.logisticsProvider | The logistics provider of the shipping | AN255 [\s\S]{1,255} |
Optional |
shipping.trackingNumber | The tracking number of the shipping | AN255 [\s\S]{1,255} |
Optional |
shipping.returnTrackingNumber | The tracking number issued for returns | AN255 [\s\S]{1,255} |
Optional |
shipping.normalized | The normalized shipping address. | AN255 [\s\S]{1,255} |
Optional |
shipping.validationStatus | Indicates whether a address got validated and normalized address got confirmed by the consumer | AN255 [\s\S]{1,255} |
Optional |
shipping.warehouse | The warehouse that fulfilled the order | AN100 [\s\S]{1,100} |
Optional |
shipping.preference | Indicates the shipping preference. Possible values:
|
AN21 GET_FROM_FILE|NO_SHIPPING|SET_PROVIDED_ADDRESS |
Optional |
shipping.middleName | The middle name for the shipping address | AN [\s\S] |
Optional |
shipping.companyName | The company name for the shipping address | AN60 [\s\S]{1,60} |
Optional |
shipping.phone | The phone number for shipping address | AN25 [+0-9][0-9 \.()/-]{5,25} |
Optional |
shipping.workPhone | The work phone number for shipping address | AN25 [\s\S]{1,25} |
Optional |
shipping.mobile | The mobile number for shipping address | AN25 [+0-9][0-9 \.()/-]{5,25} |
Optional |
shipping.email | The email address for shipping address | AN128 [\s\S]{6,128} |
Optional |
shipping.type | Defines type of shipping if return or shipment. Valid options are: RETURN, SHIPMENT |
AN8 [\s\S] |
Optional |
Merchant Shipping Address
The merchant shipping address has the same fields as shipping address, just as part of the merchant entity. That way you can ship from an entirely different merchant location.
Parameter | Description | Format | Required |
---|---|---|---|
merchant.shipping.* | All the fields that are available under shipping adress except shipping.customer.* | Same as for shipping address fields | Optional |
Corporate
The corporate data structure holds information about the corporate company for purchases made on behalf of it.
Parameter | Description | Format | Required |
---|---|---|---|
corporate.name | The name of the company | AN30 [\s\S]{1,30} |
Optional |
corporate.description | The brief description of the company | AN160 [\s\S]{1,160} |
Optional |
corporate.street | The company's address - street | AN100 [\s\S]{1,100} |
Optional |
corporate.address | The company's address - line 2 | AN100 [\s\S]{1,100} |
Optional |
corporate.city | The company's address - city | AN80 [\s\S]{1,80} |
Optional |
corporate.state | The company's address - state | AN50 [\s\S]{1,50} |
Optional |
corporate.postCode | The company's address - postal code | AN16 [\s\S]{1,16} |
Optional |
corporate.suite | The company's suite number | AN30 [\s\S]{1,30} |
Optional |
corporate.postboxNumber | The company's post box number | AN15 [\s\S]{1,15} |
Optional |
corporate.purchase | The company's purchase indicator | A1 Y|N |
Optional |
corporate.phone | The company's phone number | N25 [0-9]{1,25} |
Optional |
corporate.fax | The company's fax number | N25 [0-9]{1,25} |
Optional |
corporate.vatId | The company's vat id | AN255 [\s\S]{0,255} |
Optional |
Recipient
The recipient data structure holds information about recipient (The person who’s debt is being paid off).
Parameter / Header | Description | Format | Required |
---|---|---|---|
recipient.givenName | The first name or given name of the recipient. | AN48 [A-Za-z0-9\s]{0,48} |
Optional |
recipient.surname | The last name or surname of the recipient. | AN48 [A-Za-z0-9\s]{0,48} |
Optional |
recipient.birthDate | The birth day of the recipient in the format yyyy-MM-dd, e.g. 1970-02-17 | AN10 ([0-9]{4})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]) |
Optional |
recipient.phone | The phone number of the recipient. | AN25 [+0-9][0-9 ().-]{7,25} |
Optional |
recipient.accountNumber | The account number of the recipient. | AN32 [\s\S]{0,32} |
Optional |
recipient.street | The door number, floor, building number, building name, and street name of the recipient. | AN100 [A-Za-z0-9\s]{0,100} |
Optional |
recipient.city | The town, district or city of the recipient. | AN50 [A-Za-z0-9\s]{0,50} |
Optional |
recipient.state | The county, state or region of the recipient. | AN50 [A-Za-z0-9\s]{0,50} |
Optional |
recipient.country | The country of the recipient. | AN3 [A-Za-z0-9]{0,3} |
Optional |
recipient.postcode | The postal code or zip code of the recipient. | AN30 [\s\S]{1,30} |
Optional |
recipient.accountNumberType | Indicates type of recipient's account number. | OTHER| RTN_AND_BANK_ACCOUNT| IBAN| CARD_ACCOUNT| EMAIL| PHONE_NUMBER| BAN_AND_BIC| WALLET_ID| SOCIAL_NETWORK_ID |
Optional |
Merchant
The merchant data structure holds information about you, the merchant (acceptor). These fields can be used to override the information that is shown on the cardholder statement. It can also be used for payment facilitators.
Parameter | Description | Format | Required |
---|---|---|---|
merchant.name | The name of the merchant/acceptor. When used this field will override the value sent as Merchant Name and will normally make up the first line of the card holder statement. Typical usage would be of format {Merchant DBA Name}*{Description of product or service} .Affirm - In the Affirm No VCN flow, when the merchant passes the OPP parameter "merchant.name", the same is populated in the Affirm Checkout JSON object. This informs Affirm to display the passed in merchant name in the Welcome message on the Affirm Modal. This parameter is not applicable for the Affirm VCN flow. |
AN100 [\s\S]{1,100} |
Optional |
merchant.city | The merchant's city, phone number or email, This normally makes up the second line of the card holder statement. It is typical for card present transactions to send the city of the location of transaction and for card not present transactions to send the phone, email or url that the shopper would be recognise. |
AN100 [\s\S]{1,100} |
Optional |
merchant.street | The door number, floor, building number, building name, and/or street name of the merchant | AN100 [\s\S]{1,100} |
Optional |
merchant.postcode | The postal code or zip code of the merchant | AN16 [A-Za-z0-9\-]{1,16} |
Optional |
merchant.state | The county, state or region of the merchant | AN50 [a-zA-Z0-9]{1,50} |
Optional |
merchant.country | The merchant's two-letter country code as defined in ISO 3166-1 | A2 [A-Za-z]{2} |
Optional |
merchant.countryCode | The merchant's three-digit country code as defined in ISO 3166-1 | N3 [0-9]{3} | Optional |
merchant.phone | The merchants's phone number. | AN25 [a-zA-Z0-9\+-.]{0, 25} |
Optional |
merchant.mcc | The merchants's category code. | AN4 [a-zA-Z0-9]{0, 4} |
Optional |
merchant.submerchantId | Used only for MasterCard Payment Facilitators. The id of the sub-merchant. | AN100 [\s\S]{1,100} |
Optional |
merchant.data[key] | The additional data received from merchant alongside with transaction data. | key: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048} |
Optional |
merchant.websiteId | The website id of merchant, represents random session id unique for current transaction. | AN255 [\s\S]{0,255} |
Optional |
merchant.URL | The merchant's URL address. | AN255 [\s\S]{1,255} |
Optional |
merchant.customerContactPhone | The merchant's customer service phone number, that can be given to consumers for customer service purposes. | AN25 [a-zA-Z0-9\+-.] {0, 25} |
Optional |
merchant.partnerIdCode | The merchant's partner ID code, that represents a partnership agreement, generally between specific merchant and issuers. | AN60 [\s\S] {1,60} |
Optional |
merchant.serviceLocationCity | The merchant's service location city, where the cardholder received the services is different than the location identified by the merchant city name. | AN100 [\s\S] {1,100} |
Optional |
merchant.serviceLocationState | The merchant's service location state, where the cardholder received the services is different than the location identified by the merchant country subdivision code. | AN50 [a-zA-Z0-9] {1,50} |
Optional |
merchant.serviceLocationCountryCode | The merchant's service location country code, where the cardholder received the services is different than the location identified by the merchant country code. | AN3 [A-Za-z0-9] {0,3} |
Optional |
merchant.serviceLocationPostCode | The merchant's service location postal code, where the cardholder received the services is different than the location identified by the merchant postal code. | AN16 [A-Za-z0-9\-] {1,16} |
Optional |
merchant.isoId | The merchant's independent sales organisation ID | AN255 [\s\S]{1,255} |
Optional |
merchant.payFacId | The merchant's payment facilitator ID | AN255 [\s\S]{1,255} |
Optional |
merchant.payFacName | The merchant's payment facilitator name | AN255 [\s\S]{1,255} |
Optional |
merchant.marketplaceId | The merchant's marketplace ID | AN255 [\s\S]{1,255} |
Optional |
Cart
Cart items
The cart data structure holds product information about the shopping cart such as the product's ID, name, quantity and price.
The cart items are counted up by changing the index-number [n], starting with 0, and maximum 1000. Example: cart.items[0].name=First Cart Item
Parameter | Description | Format | Required |
---|---|---|---|
cart.items[n].name | The name of the item in the shopping cart. Example: cart.items[0].name=First Cart Item |
AN255 [\s\S]{1,255} |
Conditional |
cart.items[n].merchantItemId | The unique identifier of the item in the shopping cart. | AN255 [\s\S]{1,255} |
Conditional |
cart.items[n].quantity | The number of items in the shopping cart. | N5 [0-9]{1,12}(\\.[0-9]{0,3}) |
Conditional |
cart.items[n].type | The type of the purchased item in the shopping cart. Values can be: PHYSICAL, DIGITAL, MIXED, ANONYMOUS_DONATION, AUTHORITIES_PAYMENT | AN255 [\s\S]{1,255} |
Conditional |
cart.items[n].sku | The sku cart item. | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].currency | The currency of the price of the shopping cart. | A3 ISO 4217 currency code |
Conditional |
cart.items[n].description | The description of the item in the shopping cart. | AN2048 [\s\S]{1,2048} |
Conditional |
cart.items[n].commodityCode | L3 Card data, product commodity code. | N8 See list https://www.unspsc.org/ |
Optional |
cart.items[n].commodityDescription | L3 Card data, product commodity description. | AN50 See list https://www.unspsc.org/ |
Optional |
cart.items[n].originalPrice | The price of the item in the shopping cart. (excluding tax and discount). The item's price is independent of the quantity.. | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].price | The price of the item in the shopping cart. (including tax and discount). The item's price is independent of the quantity. | N13 [0-9]{1,10}\.[0-9]{2} |
Conditional |
cart.items[n].totalAmount | The total amount of the cart item including quantity. | N13 [0-9]{1,10}\.[0-9]{2} |
Conditional |
cart.items[n].taxAmount | The tax amount of the cart item. The item's tax amount is independent of the quantity. | N13 [0-9]{1,10}\.[0-9]{2} |
Conditional |
cart.items[n].totalTaxAmount | The total tax amount of the cart item. | N13 [0-9]{1,10}\.[0-9]{2} |
Conditional |
cart.items[n].tax | The tax percentage applied to the price of the item in the shopping cart. | AN6 ^(100(\.00?)?)|([0-9]{1,2}(\.[0-9]{1,2})?)$ |
Conditional |
cart.items[n].taxCategory | Mandatory L3 Card data tax category. | AN2 Values: AA, S, E or Z |
Conditional |
cart.items[n].shipping | The shipping amount applied to the item in the shopping cart. | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
cart.items[n].discount | The discount percentage applied to the price of the item in the shopping cart. | N13 [0-9]{1,10}\.[0-9]{2} |
Conditional |
cart.items[n].giftMessage | Gift Message for the specific cart item | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].shippingMethod | Shipping method for the cart item. | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].shippingInstructions | Shipping instructions for the cart item. | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].shippingTrackingNumber | Shipping tracking number for the cart item | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].quantityUnit | The cart item's unit of quanity. | M, CM, KG, G, COUNT (default) | Optional |
cart.items[n].productUrl | The cart item's URL. | Valid URL | Optional |
cart.items[n].imageUrl | The cart item's image URL. | Valid URL | Optional |
cart.items[n].totalDiscountAmount | The cart item's total discount amount. The total discount amount is related to the discount percentage | N10.N2[0-9]{1,10}\.[0-9]{2} | Optional |
cart.items[n].productCode | The cart item's product code given by merchant for identification | AN30 [\s\S]{1,30} |
Optional |
cart.items[n].partNumber | The cart item's manufacturer provided part number. | AN30 [\s\S]{1,30} |
Optional |
cart.items[n].itemNumber | The cart item's line number of this item on the invoice | N3 {1,999} |
Optional |
cart.items[n].vatReferenceNumber | The cart item's reference number used to identify the VAT invoice or tax receipt | AN30 [\s\S]{1,30} |
Optional |
cart.items[n].sellerId | The unique identifier of the marketplace seller to which this cart item belongs | AN255 [\s\S]{1,255} |
Optional |
cart.items[n].recipient.salutation | The cart item's recipient title | AN5 [\s\S]{1,5} |
Optional |
cart.items[n].recipient.firstName | The cart item's recipient first name | AN48 [\s\S]{1,48} |
Optional |
cart.items[n].recipient.middleName | The cart item's recipient middle name | AN50 [\s\S]{1,50} |
Optional |
cart.items[n].recipient.lastName | The cart item's recipient last name | AN48 [\s\S]{1,48} |
Optional |
cart.items[n].recipient.apartment | The cart item's recipient apartment number | AN100 [\s\S]{1,100} |
Optional |
cart.items[n].recipient.street | The cart item's recipient address line 1 | AN100 [\s\S]{1,100} |
Optional |
cart.items[n].recipient.address | The cart item's recipient address line 2 | AN100 [\s\S]{1,100} |
Optional |
cart.items[n].recipient.city | The cart item's recipient city | AN80 [\s\S]{1,80} |
Optional |
cart.items[n].recipient.state | The cart item's recipient state | AN50 [\s\S]{1,50} |
Optional |
cart.items[n].recipient.postcode | The cart item's recipient postal code | AN16 [\s\S]{1,16} |
Optional |
cart.items[n].recipient.country | The cart item's recipient country code | A2 [A-Za-z]{2} N3 [0-9]{3} |
Optional |
cart.items[n].recipient.phone | The cart item's recipient phone number | N25 [0-9]{1,25} |
Optional |
cart.items[n].recipient.email | The cart item's recipient email address | AN128 [\s\S]{1,128} |
Optional |
cart.items[n].deliveryDate | The cart item's delivery date | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Optional |
Cart payments
The cart payments data structure holds information about already made payments associated with the cart.
The cart payments are counted up by changing the index-number [n], starting with 0. Example: cart.payments[0].name=First Cart Item
Parameter | Description | Format | Required |
---|---|---|---|
cart.payments[n].name | The name of the payment methtod. Example: cart.payments[0].name=promotion giftcard 50 |
AN255 [\s\S]{1,255} |
Optional |
cart.payments[n].type | The type of the used payment. One of the options: GIFTCARD, PROMOTION Example: cart.payments[0].type=GIFTCARD |
AN255 [\s\S]{1,255} |
Optional |
cart.payments[n].amount | The amount of the associated and already used payment method. Example: cart.payments[0].amount=10.90 |
N10.N2 [0-9]{1,10}\.[0-9]{2} |
Optional |
cart.payments[n].currency | The currency of the already used payment amount. Example: cart.payments[0].currency=EUR |
A3 [a-zA-Z]{3} |
Optional |
cart.payments[n].status | The status of the already used payment method. One of the options: pending, authorized, captured Example: cart.payments[0].status=captured |
AN255 [\s\S]{1,255} |
Optional |
cart.payments[n].brand | The brand of the already used payment method, eg. SVS Example: cart.payments[0].name=SVS |
AN255 [\s\S]{1,255} |
Optional |
cart.payments[n].primary | Identifies this payment method being the primary payment method used for that cart. One of the options: true, false Example: cart.payments[0].primary=false |
true|false | Optional |
Marketplace
The marketplace data structure holds information about the sellers such as id, amount and items.
The items associated with each seller should be sent in cart items fields where each item is identified by the value in cart.items[n].sellerId field.
The sellers are counted up by changing the index-number [n], starting with 0. Example: marketPlace.sellers[0].id=2391
Parameter | Description | Format | Required |
---|---|---|---|
marketPlace.sellers[n].id | The unique identifier of the seller. | AN255 [\s\S]{1,255} |
Optional |
marketPlace.sellers[n].amount | The total amount of the items under the seller. | N13 [0-9]{1,10}\.[0-9]{2} |
Optional |
Airline
The airline data structure holds passenger and trip leg airline information.
The airline passenger and leg items are counted up by changing the index-number [n], starting with 0. Example: airline.passengers[0].name=Jane Jones
Parameter | Description | Format | Required |
---|---|---|---|
airline.totalTaxAmount | The total amount of tax | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.totalFeesAmount | The total fees | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.totalFareAmount | The total fare | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.ticketIssueDate | The date the booking/ticket was made | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Conditional |
airline.ticketIssueAddress | The address that issued the ticket | AN255 [\s\S]{1,255} |
Conditional |
airline.thirdPartyBooking | Indicates if the ticket was booked via a third party | AN255 [\s\S]{1,255} |
Conditional |
airline.bookingtype | The type of booking | AN255 [\s\S]{1,255} |
Conditional |
airline.ticketDeliveryMethod | The delivery method of the ticket | AN255 [\s\S]{1,255} |
Conditional |
airline.bookingRefNum | The booking reference number | AN255 [\s\S]{1,255} |
Conditional |
airline.agentName | The agent name | AN255 [\s\S]{1,255} |
Conditional |
airline.agentCode | The agent code | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].type | The passenger type | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].name | The name of the passenger | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].ticketRestricted | Indicates if the passenger has a restricted ticket | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].ticketNumber | The passenger's ticket number | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].status | The passenger status | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].phone | The passenger's phone | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].frequentFlyerNumber | The passenger's frequent flyer number | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].email | The passenger's email | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].dob | The passenger's date of birth | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].checkDigit | The check digit for the passenger | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].residenceCountry | The residence country code of the passenger (ISO 3166-1). | A2 ISO country code [A-Za-z]{2} |
Conditional |
airline.passengers[n].legs[n].ticketNumber | The ticket number for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].taxAmount | The tax amount for the leg | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.passengers[n].legs[n].stopOverAllowed | Indicates if a stop over is allowed | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].restrictions | Indicates if there is restrictions for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].flightNumber | The flight number for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].feesAmount | The fees for the leg | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.passengers[n].legs[n].fareBasis | The fare basis for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].fareAmount | The fare amount for the leg | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.passengers[n].legs[n].exchangeTicketNum | The exchange ticket number for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].departureTaxAmount | The departure tax amount for the leg | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
airline.passengers[n].legs[n].departureCountry | The departure country for the passenger | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].departureAirport | The departure airport for the passenger | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].airlineName | The name of the airline for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].airlineCode | The code of the airline for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].departureTime | The departure time for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].departureDate | The departure date for the leg | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Conditional |
airline.passengers[n].legs[n].arrivalCountry | The destination country for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].arrivalAirport | The destination airport for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].arrivalTime | The arrival time for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].arrivalDate | The arrival date for the leg | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Conditional |
airline.passengers[n].legs[n].couponNumber | The coupon number for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].classOfService | The class of service for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].carrierCode | The carrier code for the leg | AN255 [\s\S]{1,255} |
Conditional |
airline.passengers[n].legs[n].timeToDeparture | The airline time to departure, in days, for the leg | AN10 [\s\S]{1,10} |
Conditional |
Tokenization and Registration
As described in the Tokenization Guide there are two ways to store a customer's data on the syste. Either directly POST to the registration endpoint or add the following parameter to a payment:
Parameter | Description | Format | Required |
---|---|---|---|
createRegistration | If true, the payment details will be stored with the request. As part of the response, you will receive the parameter registration.id which you can use to reference the registration for later payments. | A5 true|false |
Optional |
overrideHolder | If true, it allows to send in the card.holder or bankAccount.holder to override the empty holder from the registration/tokenization transaction. It applies only to that particular payment and does not change the holder value of the registration transaction. For one-click payment, the edit box appears as the replacement over the empty label to allow the user to input the new value for the holder. This parameter is available on prepare (and update) checkout step of Copy & Pay as well as when sending the payment over registration one-click payment Server-to-Server. | A5 true|false |
Optional |
Recurring Migration (Deprecated)
To do a migration of recurring payment you need to do a registration (RG) with INITIAL transaction data that are send with the following parameters:
Parameter | Description | Format | Required |
---|---|---|---|
recurringMigration.paymentType | Indicates the payment type of the INITIAL request(DB|CD|PA). | A2 | Mandatory |
recurringMigration.amount | Indicates the INITIAL payment amount. | N8.N2 [0-9]{1,8}(\.[0-9]{2})? |
Optional |
recurringMigration.requestTimestamp | Indicates the timestamp of the INITIAL payment request (e.g. 2018-11-27 10:42:39+0000). | AN19 (19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1] 0[0-2]1[0-9]:0[0-5]1[0-9]:0[0-5]1[0-9] |
Conditional |
recurringMigration.connectorTxId1 | Indicates INITIAL payment response details as received from the acquirer. | AN128 [\s\S]{1,128} |
Conditional |
recurringMigration.connectorTxId2 | Indicates INITIAL payment response details as received from the acquirer. | AN128 [\s\S]{1,128} |
Conditional |
recurringMigration.connectorTxId3 | Indicates INITIAL payment response details as received from the acquirer. | AN128 [\s\S]{1,128} |
Conditional |
3D Secure
The 3D Secure data structure is used to hold authentication data generated by the 3D Secure MPI when an external MPI is being used, or additional information about the authentication.
If 3D data is present which indicates the usage of an external MPI (xid, eci, verificationId), the payment gateway will just pass through these values to the acquiring system.
For more detailed information about the required fields for 3D Secure version 2.0 and above, please visit the 3D Secure 2.0 guide here
Parameter | Description | Format | Required |
---|---|---|---|
threeDSecure.amount | Amount for which the shopper will be authenticated for | N9.N2 [0-9]{1,9}\.[0-9]{2} |
Optional |
threeDSecure.currency | Currency for which the shopper will be authenticated for | A3 ISO 4217 currency code |
Optional |
threeDSecure.eci | The ECI for the 3D Secure request. Required when using a third-party MPI Example: threeDSecure.eci=01 |
N2 0[1-8]{1} |
Conditional |
threeDSecure.verificationId | The 3D Secure CAVV or AAV. Required when using a third-party MPI. Must be Base64 encoded. |
AN28 [\s\S]{28} |
Conditional |
threeDSecure.xid | The 3D Secure xid if available. Must be Base64 encoded. | AN64 [\s\S]{64} |
Conditional |
threeDSecure.enrollmentStatus | The enrollment status for the 3D Secure request. Required when using a third-party MPI. | AN1 [YUN] |
Conditional |
threeDSecure.authenticationStatus | The authentication status for the 3D Secure request. Required when using a third-party MPI. | AN1 [YAUN] |
Conditional |
threeDSecure.deviceInfo | (Encrypted) device information. Required when initializing the 3D Secure version 2's app-based flow.
The value is obtained from the mobile SDK authRequestParams .
See 3DS SDK Standalone for more information. |
(as returned by authRequestParams ) |
Conditional |
threeDSecure.merchant.name | Merchant name as defined by the Scheme Directory Server. | AN100 [\s\S]{100} |
Optional |
threeDSecure.merchant.url | Merchant URL | AN2048 [\s\S]{0,2048} |
Optional |
threeDSecure.merchant.country | Merchant country | AN3 A3 [A-Za-z]{3} |
Optional |
threeDSecure.v2.visa.requestorId | Requestor ID for 3D Secure v2, assigned by Visa. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.visa.requestorName | Requestor Name for 3D Secure v2, assigned by Visa. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.mastercard.requestorId | Requestor ID for 3D Secure v2, assigned by Mastercard. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.mastercard.requestorName | Requestor Name for 3D Secure v2, assigned by Mastercard. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.amex.requestorId | Requestor ID for 3D Secure v2, assigned by American Express. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.amex.requestorName | Requestor Name for 3D Secure v2, assigned by American Express. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.diners.requestorId | Requestor ID for 3D Secure v2, assigned by Diners/Discover. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.diners.requestorName | Requestor Name for 3D Secure v2, assigned by Diners/Discover. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.jcb.requestorId | Requestor ID for 3D Secure v2, assigned by JCB. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.jcb.requestorName | Requestor Name for 3D Secure v2, assigned by JCB. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.cartebancaire.requestorId | Requestor ID for 3D Secure v2, assigned by Carte Bancaire. | AN100 [\s\S]{100} |
Optional |
threeDSecure.v2.cartebancaire.requestorName | Requestor Name for 3D Secure v2, assigned by Carte Bancaire. | AN100 [\s\S]{100} |
Optional |
threeDSecure.dsTransactionId | Transaction ID assigned by the directory server. Used when the transaction was already authenticated via 3D Secure v2, using an external MPI. | AN100 [\s\S]{36} |
Optional |
threeDSecure.acsTransactionId | This field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction. Used when the transaction was already authenticated via 3D Secure v2, using an external MPI. | AN100 [\s\S]{36} |
Optional |
threeDSecure.version | Version of the 3D Secure that was used when the transaction was already authenticated using an external MPI. For example: 2.1.0 or 2.2.0 | (1|2)\.[0-9]\.[0-9] | Optional |
threeDSecure.challengeIndicator | Indicates whether a challenge is requested for this transaction. Can be sent when 3D Secure version 2.2 or higher is used. | 0[1-9] | Optional |
threeDSecure.challengeMandatedIndicator | Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable. Can be used when the transaction was authenticated via an external MPI. | AN1 (Y|N) |
Optional |
threeDSecure.authType | The type of authentication that was requested by the ACS. Can be used when the transaction was authenticated via an external MPI. | AN2 0[1-4] |
Optional |
threeDSecure.exemptionFlag | Flags the transaction as exemption during authorization. Can be sent when 3D Secure version 2.2 or higher is used. | N2 0[1-4] |
Optional |
threeDSecure.transactionStatusReason | Provides information on why the Transaction Status field has the specified value. Can be used when the transaction was authenticated via an external MPI. | N2 | Optional |
threeDSecure.channel | The authentication channel indicator. Only provide to indicate 3RI request(Merchant initiated authentication), which is available as a feature in 3DS 2.2 for MasterCard only. Can be used when the transaction was authenticated via an external MPI. | N2 0?[1-9]|[1-9][0-9] |
Optional |
Custom Parameters
Custom parameters are unspecified fields that can be used to send custom data. The data sent in these fields are echoed back in the response.
Parameter | Description | Format | Required |
---|---|---|---|
customParameters[name] | A name value pair used for sending custom information. NOTE: customParameters that are sent from the client-side (e.g. for Copy & Pay) should be prepended with SHOPPER_*, for example customParameters[SHOPPER_customerId] |
name: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048} |
Conditional |
threeDSecure.schemeData[CB-ITEMSNB] | This field represents the number of items or services purchased. This field is required to process 3DS transactions for Carte Bancaire scheme and can be used for 3D Secure v2. |
N2 | Conditional but recommended |
threeDSecure.schemeData[CB-SCORE_MERCHANT] | This is the merchant score, it is calculated by the 3DS requestor and provided to card scheme scoring service only. This field is required to process 3DS transactions for Carte Bancaire scheme and can be used for 3D Secure v2. |
[a-zA-Z0-9\s+-:] {1-20} | Conditional but recommended |
threeDSecure.schemeData[CB-USECASE] | This is payment authentication use case. It indicates the type of payment for which an authentication is requested. This field is required to process 3DS transactions for Carte Bancaire scheme and can be used for 3D Secure v2. |
N2 | Conditional (required if message category = PA, or message category = NPA and 3DS requestor authentication indicator = 02 or 03) |
Asynchronous payments
Asynchronous payment methods like 3D Secure, online transfer or virtual wallets have additional steps in their workflow. The response to your initial payment request will be pending and contain a redirect URL to the receiver system that the shopper should be forwarded to.
Parameter | Description | Format | Required |
---|---|---|---|
shopperResultUrl | This URL will receive the result of an asynchronous payment. It is used to redirect the shopper to the merchant’s website or application. Must be sent URL encoded and only absolute URLs are supported. |
AN2048 [\s\S]{6,2048} |
Conditional |
notificationUrl | Deprecated. Please follow webhooks configuration and don’t use the request parameter “notificationUrl”. Due to the huge variety of payment workflows and checkout options, the notificationUrl parameter is not fully compatible with all activities. Please use webhook notifications instead.
This URL will receive the asynchronous notification where applicable. It is used to receive the transaction status update on asynchronous payments. Must be sent URL encoded. . |
AN2048 [\s\S]{6,2048} |
Optional |
The response parameters:
Parameter | Description | Format | Required |
---|---|---|---|
redirect.url | URL the the shopper must be redirected to in order to proceed. | AN2048 [\s\S]{6,2048} |
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. | AN255 [\s\S]{1,255} |
Conditional |
redirect.parameters[n].value | The parameter values corresponding to the names as described above. | AN255 [\s\S]{1,255} |
Conditional |
Webhook Notifications
When you register a webhook, you'll receive notifications on the registered Url. These notifications are basically standard responses (wrapped in the "payload") of different types.
Parameter | Description | Format | Required |
---|---|---|---|
type | Type of notification
|
PAYMENT| REGISTRATION |
Required |
action |
Indicator of status change
|
CREATED| UPDATED| DELETED |
Conditional |
payload | Content of notification. If the notification type is payment or registration, payload will be identical to payment response you received. | JSON | Required |
In addition to standard response parameters, these notifications specific are available:
Parameter | Description | Format | Required |
---|---|---|---|
presentationAmount | The presentation amount of the request. | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
presentationCurrency | The presentation currency of the request. | A3 [a-zA-Z]{3} |
Conditional |
Point Of Sale (POS)
The POS data structure holds information about transaction initiated with POS-terminal.
Parameter | Description | Format | Required |
---|---|---|---|
pos.deviceId | Serial number of the terminal. | N32 [0-9]{1,32} |
Optional |
pos.deviceType | Terminal type. Possible values: MIURA_SHUTTLE, MIURA_M007, MIURA_M010, VERIFONE_E105, VERIFONE_E315, VERIFONE_E335 |
AN32 [a-zA-Z0-9_]{1,32} |
Optional |
pos.encryptedPin.data | Encrypted online PIN data. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.encryptedPin.ksn | Key serial number to decrypt online PIN. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.encryptedSred.data | Encrypted account data (PAN/TRACK2/EXPIRY). SRED stands for "Secure Reading and Exchange of Data". |
AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.encryptedSred.ksn | Key serial number to decrypt account data. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.entryMode | What interface was used by the terminal for the transaction. Possible values: MANUAL, MAGSTRIPE, MAGSTRIPE_AS_FALLBACK, ICC, NFC_ICC, NFC_MAGSTRIPE. |
AN32 [a-zA-Z0-9_]{1,32} |
Required |
pos.iccDataRequest | Additional data returned by the card, including ARQC. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.location.accuracy | GPS accuracy. | N32 [0-9]{1,32} |
Optional |
pos.location.latitude | Latitude by GPS. | N12 \-?[0-9]{0,1}[0-9]{1}\.[0-9]{1-8} |
Optional |
pos.location.longitude | Longitude by GPS. | N13 \-?[0-1]?[0-9]{1,2}\.[0-9]{1-8} |
Optional |
pos.panSequenceNumber | Sequence number of the card, in case multiple were issued with the same PAN. | N32 [0-9]{1,32} |
Optional |
pos.pinEntryCapability | Indicates if the terminal is currently able to handle PIN. Possible values: PIN_ENTRY_AVAILABLE, PIN_ENTRY_UNAVAILABLE. |
AN32 [a-zA-Z0-9_]{1,32} |
Optional |
pos.terminalId | Id assigned by the acquirer. | N32 [0-9]{1,32} |
Required |
pos.transactionSequenceNumber | Sequence number of the transaction, incremented after each transaction by the terminal. | N32 [0-9]{1,32} |
Optional |
pos.transactionSource | Indicator that this is a POS transaction. Currently should be always POS. |
A3 POS |
Optional |
The response parameters:
Parameter | Description | Format | Required |
---|---|---|---|
pos.clearing.authorizationAcquirerCode | Code assigned by the acquirer. Used to print receipts. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.clearing.authorizationIssuerCode | Code assigned by the issuer. Used to print receipts. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.clearing.identifier | Transaction identifier assigned by the acquirer. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.merchantId | Merchant identifier assigned by the acquirer. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.iccDataResponse | Data returned by the issuer that has to be returned to the card, including ARPC. | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.statusText | Text that has to be additionally printed on the receipt (instead of approved/declined). | AN2048 [a-zA-Z0-9]{1,2048} |
Optional |
pos.timestamp | Timestamp of the transaction with the acquirer. | date yyyy-MM-dd hh:mm:ss |
Optional |
Reporting
The following parameters are used when calling the reporting endpoints.
Parameter | Description | Format | Required |
---|---|---|---|
date.from | The date from which the report data should start | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Required |
date.to | The date on which the report data should end | AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Required |
sortValue | The value based on which Detail Level settlement report is sorted | SettlementTxDate | Optional |
sortOrder | The order in which Detail Level settlement report output is sorted | ASC|DESC|asc|desc | Optional |
Giftcard
A giftcard allows you to send additional information for payments and risk checks that have a gift card.
Parameter | Description | Format | Required |
---|---|---|---|
giftCard.number | The gift card number. | AN255 [\s\S]{2,255} |
Optional |
giftCard.pin | The gift card pin number. | AN255 [\s\S]{2,255} |
Optional |
giftCard.holder | The holder of the gift card. | AN255 [\s\S]{2,255} |
Optional |
giftCard.message | Message that should be written on the gift card. | AN160 [\s\S]{2,160} |
Optional |
giftCard.type | Type of the Gift Card. One of the options: ANNIVERSARY, BIRTHDAY, CONGRATULATIONS, APRIL_FOOLS_DAY, EASTER, FATHERS_DAY, GRADUATION, HOLIDAY, SEASONS_GREETINGS, PASSOVER, KWANZAA, HALLOWEEN, MOTHERS_DAY, NEW_YEARS_DAY, BOSSES_DAY, ST_PATRICKS_DAY, SWEETEST_DAY, CHRISTMAS, BABY_SHOWER, THANKSGIVING, OTHER, VALENTINES_DAY, WEDDING, SECRETARYS_DAY, CHINESE_NEW_YEAR, HANUKKAH, CELEBRATE_FALL, GRANDPARENTS_DAY, INDEPENDENCE_DAY | AN16 | Optional |
Risk
The following parameters are additional parameters available for risk checks e.g. using the ReD Shield.
Parameter | Description | Format | Required |
---|---|---|---|
risk.channelId | Id of the channel in the risk system. This field is usually set up as a configuration, but in some situations you might want to use the dynamic request based option described here. For the ReD Shield this will cause a different set of rules to be executed. There the length is limited to AN12. |
AN255 [\s\S]{1,255} |
Optional |
risk.serviceId | Id of the service in the risk system. This field is usually set up as a configuration, but in some situations you might want to use the dynamic request based option described here. For the ReD Shield this defines which fraud screening service to use. There the length is limited to AN1. |
AN255 [\s\S]{1,255} |
Optional |
risk.amount | Amount for the risk request. The dot is used as decimal separator. Currently this parameter is used for both ReD Shield and 3D Secure. When performing the 3D Secure, if this parameter is present, its value will be used as the amount for the 3D Secure. |
N10.N2 [0-9]{1,10}\.[0-9]{2} |
Optional |
risk.orderTimestamp | Timestamp of the order for the risk request. Format: yyyy-MM-dd hh:mm:ss (24h clock), e.g. 2015-12-17 22:00:04 By default our payment system sets a timestamp automatically. Use this field when the (payment) transaction was executed at a different time than sending the risk request at hand. |
AN19 {(19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1] 0[0-2]1[0-9]:0[0-5]1[0-9]:0[0-5]1[0-9] } |
Optional |
risk.brand | Brand of the payment that is being checked. By default you can use the field paymentBrand instead of this one. However, if the payment isn't executed through the OPP you might have a different brand-format you can specify here. | AN255 [\s\S]{1,255} |
Optional |
risk.parameters[name] | A name value pair used for sending custom information related to the risk request. | name: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048} |
Optional |
risk.merchantWebsite | Merchant's website URL | AN60 [\s\S]{1,60} |
Optional |
risk.accountToken | A merchant-set token for the account | AN64 [\s\S]{1,64} |
Optional |
Scheduling
The following parameters can be used to schedule subscription payment jobs.
Specifying both a dayOfWeek and a dayOfMonth value is not supported. You'll need to use the '?' character in one of these fields.
Parameter | Description | Format | Required |
---|---|---|---|
job.name | The name of the job to be scheduled. Used for identification purposes only. | AN64 [\s\S]{1,64} |
Optional |
job.year | The specific year to execute | AN64 empty, 1970-2099 , - * / The default value is * |
Optional |
job.month | The specific month to execute (Jan - Dec) | AN64 1-12 , - * / The default value is 1 |
Optional |
job.dayOfMonth | The specific day in the month to execute | AN64 1-31 , - * ? / L W The default value is 1 |
Optional |
job.dayOfWeek | The specific day in the week to execute | AN64 1-7 SUN-SAT , - * ? / L # The default value is 1 |
Optional |
job.hour | The specific hour to execute | AN64 0-23 , - * / The default value is 0 |
Optional |
job.minute | The specific minute to execute | AN64 0-59 The default value is 0 |
Optional |
job.second | The specific second to execute | AN64 0-59 , - * / The default value is 0 |
Optional |
job.startDate | The date/time the job should be executed | AN19 yyyy-MM-dd HH:mm:ss |
Optional |
job.endDate | The date/time the job should be ended | AN19 yyyy-MM-dd HH:mm:ss |
Optional |
job.noticeUnit | The unit of the cancellation notice period | YEAR|MONTH|WEEK|DAY| HOUR|MINUTE|SECOND |
Optional |
job.noticeNumber | The time in advance required by the cancellation notice to be given to avoid a prolongation of the job period | N16 | Optional |
job.noticeCallable | The reference point for the cancellation notice | ANYTIME|DURATION_END | Optional |
job.durationUnit | The unit of the job period duration | YEAR|MONTH|WEEK|DAY| HOUR|MINUTE|SECOND |
Optional |
job.durationNumber | The duration of the job period | N16 | Optional |
job.expression | The Cron-Expression representing how often the job will execute. A Cron-Expression is a string comprised of 7 fields, while the job.year can be left out. It will overwrite second, minute, hour, dayOfMonth, month, dayOfWeek and year in this order. | AN256 | Optional |
Payment Response Parameters
Parameter | Description | Format | Required |
---|---|---|---|
id (/checkouts) | The identifier of the checkout request that can be used to reference the payment later. You get this as the field id of a checkout's response and then should use it as the {id} part in step 2 and step 3 of the integration guide. |
AN48 [a-zA-Z0-9.\-]{32,48} |
required |
id (/payments) | The identifier of the payment request that can be used to reference the payment later. You get this as the field id of a payment's response and then can use it as referencedPaymentId in the backoffice tutorial or as the {id} part of the URL for sending referencing requests. |
AN32 [a-zA-Z0-9]{32} |
required |
id (/registrations) | The identifier of the registration 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). You should use it for requests referencing this registration as the {id} part of the URL. |
AN32 [a-zA-Z0-9]{32} |
required |
referencedId | In case of referenced payment (e.g., Capture or Refund), this fields included to see which payment was referenced. Note: This fields is only for webhook notification. |
AN32 [a-zA-Z0-9]{32} |
Conditional |
paymentBrand | The payment brand of the request. | AN32 [a-zA-Z0-9_] {1,32} |
Conditional |
amount | The amount of the transaction approved by the acquirer, alternative payment method or other payment platform. | N10.N2 [0-9]{1,10}\.[0-9]{2} |
Conditional |
currency | The currency of the request. | A3 [a-zA-Z]{3} |
Conditional |
descriptor | The descriptor of the request. | AN127 [\s\S]{1,127} |
Conditional |
result.code | The unique code that indicates the result status of the request. See the result codes for more detailed information. | AN11 [0-9\.]{2,11} |
Required |
result.description | A textual description explaining the result.code's meaning. | AN255 [\s\S]{0,255} |
Optional |
result.avsResponse | Contains the AVS response returned by the acquirer. It may include one the following result: A = Address does match, zip code does not match Z = Address does not match, zip code does match N = Address and zip code do not match U = Technical or logical error. AVS cannot be applied on card or address (not UK or US issuer), issuer is not available, etc. F = Address and Postal Code Matches |
A1 [A-Z]{1} |
Conditional |
result.cvvResponse | Contains the CVV response returned by the acquirer. It may include one the following result:
| A1 [A-Z]{1} |
Conditional |
resultDetails | A container for name value pair used for enriching the response with bank-specific response details. I.e. the actual parameters used within resultDetails are bank-specific. Example: resultDetails.AuthCode=123456 |
name: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048} |
Optional |
resultDetails.AcquirerResponse | Represents the acquirer original response code retrieved from the acquirer directly. | AN2048 [\s\S]{0,2048} |
Conditional |
resultDetails.MerchantAdviceCode | Represents information regarding reason of decline and next actions for a transaction. (Note: Check individual integration sheet to ensure if any specific integration supports this field) |
N2 [\d]{2} |
Optional |
card.bin | The first six digits of the card.number | N6 [\d]{6} |
Optional |
card.holder | Holder of the credit card account | N6 [\d]{6} |
Optional |
card.expiryMonth | The expiry month of the card | N6 [\d]{2} |
Optional |
card.expiryYear | The expiry year of the card | N4 [\d]{4} |
Optional |
card.issuer.bank | The issuer name | AN2048 [\s\S]{0,2048} |
Optional |
card.issuer.phone | The phone number of the issuer | AN2048 [\s\S]{0,2048} |
Optional |
card.issuer.website | The website of the issuer | AN2048 [\s\S]{0,2048} |
Optional |
card.type | The type of the card, eg. CREDIT | AN2048 [\s\S]{0,2048} |
Optional |
card.level | The level of the card, eg. DEFERRED DEBIT | N4 [\d]{4} |
Optional |
card.regulatedFlag | Regulated or unregulated, eg. true|false | AN2048 [\s\S]{0,2048} |
Optional |
merchant.bankAccount.holder | Holder of the merchant's bank account | AN128 {4,128} |
Required |
merchant.bankAccount.number | The account number of the merchant's bank account. (IBAN for SEPA accounts) | AN64 [a-zA-Z0-9]{3,64} |
Conditional |
merchant.bankAccount.bic | The BIC (Bank Identifier Code (SWIFT)) 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 (ISO 3166-1). | AN2 [a-zA-Z]{2} |
Conditional |
risk.score | Returns the score of the executed transaction risk checks. The value is a number from -99999 to +99999. Can be returned both for standalone risk requests and payment requests that include risk checks. | AN6 [-+]?[0-9]{5} |
Conditional |
Other | The response can also contain each of the data structures listed above, such as customer and billingAddress . |
n/a | Conditional |
buildNumber | Useful for support purposes. | AN255 [\s\S]{0,255} |
Required |
timestamp | The timestamp the response has generated. | date yyyy-MM-dd hh:mm:ssZ |
Required |
ndc | An internal unique identifier for the request. | AN69 [a-zA-Z0-9\-]{1,69} |
Required |
brandResult | Detected brand | A16 | optional |
Reconciliation Response Parameters
Reconciliation reporting data is available via CSV file from FTP. The structure of the reconciliation reporting csv file is as of following:
ReconciliationType;PaymentType;Cashflow;ClearingInstituteMerchantId;MerchantAccountId;MerchantAccountName;PspId;DivisionId;MerchantId;SettlementTxId;UniqueID;ShortId;ConnectorTxId1;ConnectorTxId2;ConnectorTxId3;Amount;Currency;Brand;TxRequestTime;SettlementAmount;SettlementCurrency;SettlementFee;SettlementFxRate;SettlementDate;SettlementStatus;Descriptor;AccountNumberLast4;BankCode;AccountHolder;ReasonCode;ReasonDesc;SettlementFileFormat;ClearingInsitituteName;MatchingStatus;MatchedTransactions;ChargebackId
Parameter CSV | Parameter API | Description | Format | Required |
---|---|---|---|---|
ReasonCode | result.code | Failure Status Code (available only for Chargebacks) | AN11 [0-9\.]{2,11} |
optional |
ReasonDesc | result.description | Failure Status Description (available only for Chargebacks) | AN128 | optional |
SettlementTxId | settlement.id | Transaction ID at Settlement Provider | AN64 [\s\S]{0,64} |
optional |
Cashflow | settlement.cashflow | Transaction Balance Direction | POS, NEG | required |
SettlementAmount | settlement.amount | Settled Amount | N13 [0-9]{1,10}\.[0-9]{2} |
required |
SettlementCurrency | settlement.currency | Settlement Currency | A3 (according to ISO 4217) | required |
SettlementFee | settlement.fee | Settlement Fee | N13 [0-9]{1,10}\.[0-9]{2} |
optional |
SettlementFxRate | settlement.fxRate | Settlement FX Rate | N13 [0-9]{1,10}\.[0-9]{2} |
required |
SettlementDate | settlement.date | Date on which settlement is executed by the Clearing Institute in its time zone | required | |
SettlementStatus | settlement.status | Settlement Status | SUCCESS, FAILED | required |
SettlementFileFormat | settlement.format | File format of Settlement File | AN32 | required |
ClearingInsitituteName | clearingInstitute.name | Name of Clearing Institute | AN64 | required |
ClearingInstituteMerchantId | clearingInstitute.merchantId | Merchant ID at Settlement Provider | AN64 [\s\S]{5..64} |
required |
ConnectorTxId1 | clearingInstitute.txId1 | Additional field for a transaction related reference (provided by the Clearing Institute) | AN64 | optional |
ConnectorTxId2 | clearingInstitute.txId2 | Additional field for a transaction related reference (provided by the Clearing Institute) | AN64 | optional |
ConnectorTxId3 | clearingInstitute.txId3 | Additional field for a transaction related reference (provided by the Clearing Institute) | AN64 | optional |
AccountNumberLast4 | card.last4Digits | Last 4 digits of the credit/debit card | AN4 | optional |
AccountHolder | card.holder | Account Holder of credit/debit card acount | AN128 | optional |
AccountNumberLast4 | bankAccount.last4Digits | Last 4 digits of the bank account | AN4 | optional |
BankCode | bankAccount.bankCode | Bank Code/BIC in case the transaction is bank related | AN12 | optional |
AccountHolder | bankAccount.holder | Account Holder of bank acount | AN128 | optional |
MerchantAccountId | merchantAccount.id | Account ID of Merchant | AN32 [a-zA-Z0-9]{32} |
required |
MerchantAccountName | merchantAccount.name | Name of Merchant | AN32 [a-zA-Z0-9]{32} |
optional |
UniqueID | payment.id | Unique ID of payment transaction in gateway | AN32 [a-zA-Z0-9]{32} |
optional |
ReconciliationType | recordType | Type of the record | SETTLED, CHARGEBACK, CHARGEBACK REVERSAL, FEE | required |
PaymentType | transactionType | Type of Transaction | DEBIT, CREDIT, REFUND, BATCH, MONTHLY, SUBMERCHANT, PAYMENT_FACILITATOR, AUTH_FEE, CAPTURE_FEE, CANCEL_FEE, REFUND_FEE | required |
PspId | pspEntityId | ID of PSP | AN32 [a-zA-Z0-9]{32} |
required |
DivisionId | divisionEntityId | ID of Division | AN32 [a-zA-Z0-9]{32} |
optional |
MerchantId | merchantEntityId | ID of Merchant | AN32 [a-zA-Z0-9]{32} |
required |
ShortId | - | Short Id of payment transaction in gateway | AN14 | optional |
TransactionId | merchantTransactionId | Unique reference number provided by merchant or generated by the gateway | AN255 [\s\S]{8,255} |
required |
InvoiceId | merchantInvoiceId | Invoice ID provided by merchant | AN255 [\s\S]{8,255} |
optional |
Amount | amount | Transaction amount | N13 [0-9]{1,10}\.[0-9]{2} |
required |
Currency | currency | Transaction Currency | A3 (according to ISO 4217) | required |
Brand | paymentBrand | Brand of the payment method | A16 | optional |
TxRequestTime | presentmentDate | Time of ordering the transaction by the merchant in Clearing Institute’s time zone. The value can be either retrieved from a specific field in the received settlement file. Or in case no specific field is identified/mapped the default code is utilized which is the timestamp when the acquirer file is parsed on our system. (i.e. the timestamp of the recon job) |
optional | |
Descriptor | descriptor | Transaction Reference which appears on the end customer’s statement | AN128 | optional |
MatchingStatus | matchedTransactions.status | The matching status of the corresponding transaction within the gateway | MATCHED, MULTIPLE_MATCHES, NOT_MATCHED | conditional |
MatchedTransactions | matchedTransactions.payment[n].id | Unique ID(s) of the matched transactions | AN32 [a-zA-Z0-9]{32} |
conditional |
ChargebackId | chargebackTransaction.id | The Unique ID of the Chargeback transaction generated by the gateway after matching a chargeback record. | AN32 [a-zA-Z0-9]{32} |
conditional |
Card On File
Following are all the parameters needed for sending card on file transactions.
Parameter | Description | Format | Required |
---|---|---|---|
standingInstruction.type | The category of the transaction.
|
UNSCHEDULED|INSTALLMENT|RECURRING | Conditional |
standingInstruction.recurringType | Indicates the type of a recurring MIT agreement.
|
STANDING_ORDER|SUBSCRIPTION | Conditional |
standingInstruction.mode | Indicating the mode of subsequent payment transaction.
|
INITIAL|REPEATED | Conditional |
standingInstruction.source | Indicating the type of subsequent payment transaction.
|
CIT|MIT | Conditional |
standingInstruction.initialTransactionId | The value/ID is received as part of the acquirer response of a CIT flagged transaction.Depending on the acquirer the ID is received either in OPP response field:
|
AN or N(No specific format-Depends on acquirer) | Conditional |
standingInstruction.industryPractice | The MIT types defined under this category are performed to fulfill a business practice as a follow-up to an original cardholder-merchant interaction that could not be completed with one single transaction.
|
INCREMENTAL_AUTH|RESUBMISSION|REAUTHORIZATION|DELAYED_CHARGES|NO_SHOW | Conditional |
standingInstruction.expiry | Date after which no further authorizations will be performed. Used for authentication request during EMV 3D.
|
yyyy-mm-dd | Conditional |
standingInstruction.frequency | Indicates the minimum number of days between authorizations.
|
N4 | Conditional |
standingInstruction.numberOfInstallments | Indicates the maximum number of authorizations permitted for installment payments. Required if the Merchant and Cardholder have agreed to installment payments, and EMV 3D authentication is configured i.e. if standingInstruction.type=INSTALLMENT. Omitted if not an instalment payment authentication. Note: This parameter is conditional (mandatory when processing 3D Secure on installment transactions). | N3 | Conditional |
Chargeback
The following parameters can be used for chargeback back-office operations.
Parameter | Description | Format | Required |
---|---|---|---|
chargebackResultCode | The chargeback reason code for the chargeback as received separately from the acquirer. See the chargeback result codes for more detailed information. | 000\.100\.2[0-9]{2} | Optional |
Query
The following parameters can be used for OPP query requests.
Parameter | Description | Format | Required |
---|---|---|---|
merchantTransactionId | The merchant reference sent in the request. Normally used to identify an order in the order management system and used as end-to-end identifier for reconciliation. It cannot be used when query for a time frame using date.from /date.to parameters |
AN255 | Optional |
limit | The maximum number of transactions to be returned in query response. | Numeric values between 100 and 500. If the value is not set explicitly, the system will use 100 as default value. | Optional |
date.from | The start timestamp from which transactions should be queried.Should be used together with the end of interval date.to . |
yyyy-MM-dd HH:mm:ss | Optional |
date.to | The end timestamp before which transactions should be queried.Should be used together with the start of interval date.from . |
yyyy-MM-dd HH:mm:ss | Optional |
paymentTypes | Indicates payment types by which transactions should be filtered. Possible values are: CB,CD,CR,DB,CP,IV,PA,RB,RC,RF,RL,RV,AD,IN,FI,CL,CF,DR,RG,RR,TE,CT,DS,RS,SD,AC,MD,EA,RI,3D,SA,EN,ID,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,FO,CS,EX,SE,AU,TK,TF,ER | Comma separated list of payment typespaymentTypes=PA,DB | Optional |
paymentMethods | Indicates payment methods by which transactions should be filtered. Possibile values are: DD,CT,CC,WA,VA,UA,OT,DC,ET,NT,IV,PP,OD,RM | Comma separated list of payment methodspaymentMethods=CC,RM | Optional |
includeLinkedTransactions | Indicates whether all transactions linked with one provided in query request should be returned in a response. | true|false | Optional |
shortId | Indicates the shortId by which the transactions should be filtered | AN14 | Optional |