API Reference

API Reference

Introduction

This reference section provides you with a complete and in-depth description of the CheckoutGate 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

Show throttling details

Test system

Show throttling details

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' testing
  • testMode=INTERNAL causes transactions to be sent to our simulators.

If no testMode parameter is sent, testMode=INTERNAL is the default behaviour

Important: The API parameter testMode is only allowed to be used in the test environment. Requests sent to the production environment, with the testMode parameter present, will result in a decline with following error message:
600.200.701 - testMode not allowed on production.

Credit Card Test Accounts

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

CountryIBANBIC
Austria (AT) AT152011128161647502 GIBAATWWXXX
Germany (DE) DE23100000001234567890 MARKDEF1100
Spain (ES) ES9121000418450200051332 CAIXESBBXXX

This reference lists all the CheckoutGate Platform parameters, grouped by their data structures.

Basic Payment

ParameterDescriptionFormatRequired
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:
  • PA, Preauthorization: A stand-alone authorisation that will also trigger optional risk management and validation. A Capture (CP) with reference to the Preauthorisation (PA) will confirm the payment..
  • DB, Debit: Debits the account of the end customer and credits the merchant account.
  • CD, Credit: Credits the account of the end customer and debits the merchant account.
  • CP, Capture: Captures a preauthorized (PA) amount.
  • RV, Reversal: Reverses an already processed Preauthorization (PA), Debit (DB) or Credit (CD) transaction. As a consequence, the end customer will never see any booking on his statement. A Reversal is only possible until a connector specific cut-off time. Some connectors don't support Reversals.
  • RF, Refund: Credits the account of the end customer with a reference to a prior Debit (DB) or Credit (CD) transaction. The end customer will always see two bookings on his statement. Some connectors do not support Refunds.
 A2 Required
integrity If true, the SRI hash of the payment script will be calculated and returned in the response. This is needed to allow the browser to check the integrity of the script in accordance with PCI requirements. For more information refer to Scripts compliance page A5
true|false		 Optional
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:
  • EC - eCommerce
  • MO - Mail order
  • TO - Telephone order
  • PO - pos
  • PM - mpos
  • MOTO - Mail order Telephone order
 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
transactionLinkId Transaction Link Identifier
Used by Mastercard to help promote an improved and consistent linking of life cycle activity occurring after the original transaction and other related transactions.		 AN35
[\s\S]{1,35}		 Optional
transactionPurposeCode Transaction Purpose Code AN12
[\s\S]{1,12}		 Optional
integrationType Integration Type AN10
[\s\S]{1,10}		 Optional

Forex

ParameterDescriptionFormatRequired
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 / HeaderDescriptionFormatRequired
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.

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

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

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

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

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

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

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

ParameterDescriptionFormatRequired
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 – acquirer or external provider token
  • NETWORK – Scheme provider token
 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.

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

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

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

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

ParameterDescriptionFormatRequired
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:
  • GET_FROM_FILE - use the shipping address provided by customer at acquirer hosted pages.
  • NO_SHIPPING - no shipping is expected for the purchase. Preferred option for digital goods.
  • SET_PROVIDED_ADDRESS - use the merchant-provided address. The customer can't change this address on the acquirer hosted pages.
Default value: GET_FROM_FILE 		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.

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

ParameterDescriptionFormatRequired
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

Sender

The sender data structure holds information about sender (The person who pays the debt).

Parameter / HeaderDescriptionFormatRequired
sender.name The name of the sender. AN100
[A-Za-z0-9\s]{0,100}		 Optional
sender.givenName The first name or given name of the sender. AN50
[A-Za-z0-9\s]{0,50}		 Optional
sender.surname The last name or surname of the sender. AN50
[A-Za-z0-9\s]{0,50}		 Optional
sender.birthDate The birth day of the sender 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
sender.accountNumber The account number of the sender. AN32
[\s\S]{0,32}		 Optional
sender.street The door number, floor, building number, building name, and street name of the sender. AN100
[A-Za-z0-9\s]{0,100}		 Optional
sender.city The town, district or city of the sender. AN50
[A-Za-z0-9\s]{0,50}		 Optional
sender.state The county, state or region of the sender. AN50
[A-Za-z0-9\s]{0,50}		 Optional
sender.country The country of the sender. AN3
[A-Za-z0-9]{0,3}		 Optional
sender.accountNumberType Indicates type of sender account number. OTHER
RTN_AND_BANK_ACCOUNT
IBAN
BAN_AND_BIC
CARD_ACCOUNT 		Optional
sender.sourceOfFunds The source of funds of the sender. N2
01 - Visa Credit
02 - Visa Debit
03 - Visa Prepaid
04 - Cash
05 - Debit/deposit access accounts other than those linked to a Visa card
06 - Credit accounts other than those linked to a Visa card		 Optional

Recipient

The recipient data structure holds information about recipient (The person who’s debt is being paid off).

Parameter / HeaderDescriptionFormatRequired
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.

ParameterDescriptionFormatRequired
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.mcc The merchants's category code. AN4
[a-zA-Z0-9]{0, 4}		 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.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.state The county, state or region of the merchant AN50
[a-zA-Z0-9]{1,50}		 Optional
merchant.countryCode The merchant's three-digit country code as defined in ISO 3166-1 N3 [0-9]{3} Optional
merchant.country The merchant's two-letter country code as defined in ISO 3166-1 A2
[A-Za-z]{2}		 Optional
merchant.postcode The postal code or zip code of the merchant AN16
[A-Za-z0-9\-]{1,16}		 Optional
merchant.geographicCoordinates Merchant Geographic Coordinates contains the latitude and longitude of the merchant's location.
ex: 61.21630,-149.89500		 NS20
{1,20}		 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.serviceLocationGeographicCoordinates Service Location Geographic Coordinates contains the latitude and longitude where the cardholder received the service, if it is different from the merchant's location.
ex: 61.21630,-149.89500		 NS20
{1,20}		 Optional
merchant.additionalContact The merchant's additional contact information AN255
[\s\S]{1,255}		 Optional
merchant.phone The merchants's phone number. AN25
[a-zA-Z0-9\+-.]{0, 25}		 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.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.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.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.submerchantId Used only for MasterCard Payment Facilitators. The id of the sub-merchant. AN100
[\s\S]{1,100}		 Optional
merchant.marketplaceId The merchant's marketplace ID AN255
[\s\S]{1,255}		 Optional
merchant.taxId The merchant's tax id information AN60
[\s\S] {1,60}		 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.foreignRetailIndicator The merchant's Foreign Retail Indicator AN25
[\s\S]{1,25}		 Optional
merchant.legalName The merchant's Legal name AN100
[\s\S]{1,100}		 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

ParameterDescriptionFormatRequired
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

ParameterDescriptionFormatRequired
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

ParameterDescriptionFormatRequired
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

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

ParameterDescriptionFormatRequired
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 COPYandPAY 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:

ParameterDescriptionFormatRequired
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

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

ParameterDescriptionFormatRequired
customParameters[name] A name value pair used for sending custom information.
NOTE: customParameters that are sent from the client-side (e.g. for COPYandPAY) 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.

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

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

ParameterDescriptionFormatRequired
type Type of notification
  • PAYMENT This type of notification is sent when payment is created or updated in the system.
  • REGISTRATION This type of notification is sent when we get new registration request, or the existing registration has been deleted.
 PAYMENT|
REGISTRATION		 Required
action Indicator of status change
  • CREATED e.g., When registration has been created.
  • UPDATED e.g., When registration has been updated.
  • DELETED e.g., When registration has been deleted.
 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:

ParameterDescriptionFormatRequired
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

Reporting

The following parameters are used when calling the reporting endpoints.

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

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

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

Important: The API response is in a JSON format. This approach allows us to be flexible in extending the API schema by adding new fields at any time to add a new product functionality. Please ensure your integration is parsing the JSON response properly and is able to handle newly added response fields without any service interruption

ParameterDescriptionFormatRequired
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:
  • M - CVV2 Match
    Indicates that the issuer was able to verify the CVV2 value provided by the merchant.
  • N - CVV2, CVC2, Discover CID or AMEX CID do not match
    Indicates that the issuer was not able to verify the CVV2 value provided by the merchant.
  • P - Not Processed
    Indicates that the issuer was unable to verify the CVV2 value provided by the merchant because either their verification system was not functioning, or not all of the information needed to verify the CVV2 value (such as the expiration date) was included in the request.
  • S - CVV2, CVC2, Discover CID or AMEX CID data is not present on the card, but the issuer indicated it should be present
    Indicates that the issuer was unable to perform CVV2 verification, and notifies the merchant that the card should contain a CVV2 value.
  • U - Unsupported by issuer or issuer is unable to process request
    Indicates that the issuer is not participating in the CVV2 service, or that the issue has not provided the card Brand with the required encryption keys needed to perform verification, or that STIP has responded with unavailable response.
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.

ParameterDescriptionFormatRequired
standingInstruction.type The category of the transaction.
  • RECURRING: Recurring Transactions are transactions that are processed on a regular fixed interval for a pre-agreed or advised amount, where applicable. Recurring Transactions don't have a fixed duration and will continue to be processed until the cardholder cancels the agreement.
  • INSTALLMENT: Installment Payments are transactions that are processed on a regular fixed interval for a pre-agreed amount for a single purchase of good or services. Unlike Recurring Transactions, Installment Payments do have a fixed duration and shouldn't continue to be processed after the end of the agreed installment period.
  • UNSCHEDULED: An unscheduled credential-on-file transaction is like a recurring transaction but differs in that it does not happen at pre-agreed intervals. The classic example of such a transaction is when it is triggered by an event such as an amount threshold to ensure that a pay-as-you-go account always has a minimum available reserve.
 UNSCHEDULED|
INSTALLMENT|
RECURRING		 Conditional
standingInstruction.recurringType Indicates the type of a recurring MIT agreement.
  • STANDING_ORDER: value has to be provided in case the consumer agrees to store the credential-on-file and initiates the first transaction in a series intended to be for a variable amount and a fixed frequency. Example: The initial transaction to store the credential-on-file for a monthly utility payment.
  • SUBSCRIPTION: value has to be provided in case the consumer agrees to store the credential-on-file and initiates the first transaction in a series intended to be for a fixed amount and a fixed frequency. Example: The initial transaction to store the credential-on-file for a monthly newspaper subscription.
Note - This value is conditional, it is required for:
  • All Mastercard CIT and MIT
  • Visa Recurring transactions executed with cards issued in India
 STANDING_ORDER|
SUBSCRIPTION		 Conditional
standingInstruction.mode Indicating the mode of subsequent payment transaction.
  • INITIAL: The payment is the first of a series of payments. This first payment must contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request.
  • REPEATED: The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters - the shopper is not present anymore.
 INITIAL|
REPEATED		 Conditional
standingInstruction.source Indicating the type of subsequent payment transaction.
  • CIT: Cardholder initiated transaction.
  • MIT: Merchant initiated transaction.
 CIT|
MIT		 Conditional
standingInstruction.initialTransactionId The field represents the reference ID generated by the scheme (in some integrations, the processor provides its own internal ID instead of the scheme value) for the transaction, and is returned by the processor/acquirer as part of the CIT transaction response.
The ID is received in one of below OPP response fields, depending on the integration (refer to respective Connector Integration sheet):
  • 'standingInstruction.initialTransactionId'
  • 'resultDetails.CardholderInitiatedTransactionID'

The field is required in the MIT transactions, when the card isn't tokenized by our platform.		 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: Incremental authorizations can be used to increase the total amount authorized. Incremental authorizations do not replace the original authorization — they are additional to previously authorized amounts — the sum of all linked estimated and incremental authorizations represent the total amount on hold in the cardholder’s account for a given transaction.
  • RESUBMISSION: When a merchant attempts to authorize a transaction after the service has been used but the issuer declines it for insufficient funds, they may attempt to re-authorize to recover the debt. These authorization requests are considered resubmission authorizations and must carry the new “re submission” indicator.
  • REAUTHORIZATION: Re-authorization occurs when a merchant has a need to submit an authorization request after the cardholder has left the point of interaction and there is no possibility of re-authenticating the card or the cardholder. A merchant may need to do this if they intend to split the shipment into multiple deliveries and will only authorize as goods come into stock. If the need to re-authorize occurs, the subsequent authorization requests carry the new “re-authorization” marker and the scheme reference data from the initial interaction.
  • DELAYED_CHARGES and NO_SHOW: Such transactions occur largely in the rental and hospitality sectors. These transactions also carry the scheme reference data provided in the initial authorization at the start of the rental or stay agreement as well as in the settlement record.
 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.
  • For MasterCard - : If the parameter is not sent by the customer, the platform adds a default value of 9999-12-31 within the authentication request.
  • For other brands -: if the parameter is not sent by the customer, the platform sends an authentication request with indicator "payment" (not "recurring").
Note: This parameter is conditional (mandatory when processing 3D Secure on recurring or installment transactions). 		yyyy-mm-dd Conditional
standingInstruction.frequency Indicates the minimum number of days between authorizations.
  • For MasterCard - : If the parameter is not sent by the customer, the platform adds a default value of 0001 within the authentication request.
  • For other brands -: if the parameter is not sent by the customer, the platform sends an authentication request with indicator "payment" (not "recurring").
Note: This parameter is conditional (mandatory when processing 3D Secure on recurring or installment transactions). 		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.

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

ParameterDescriptionFormatRequired
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 types
paymentTypes=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 methods
paymentMethods=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