API Parameters Reference

Introduction

This reference section provides you with a complete and in-depth description of the PrimeiroPayment Platform API.‌

​Hosts​

  • Test: https://test.oppwa.com/

  • Live: https://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.‌

​Testing​

It is important to note that we have two test modes available to cause requests to be sent to our connector simulator or to the connector's 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, which is useful when switching to the live endpoint for connectivity testing.

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 PrimeiroPayment 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

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

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

  • RC - Recurring

  • IN - Installment

  • PO - pos

  • PM - mpos

AN32 [a-zA-Z0-9]{0,32}

Optional

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.

N19 [0-9]{12,19}

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

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

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. Will be truncated after 48 characters

AN [\s\S]

Conditional

customer.middleName

The middle name of the customer.

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. Will be truncated after 48 characters

AN [\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 \.()/-]{7,25}

Optional

customer.mobile

The customer's mobile number. Required for some risk checks.

AN25 [+0-9][0-9 \.()/-]{5,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.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 3DS 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 3DS v2.

[\s\S]{1,8}

Conditional

​Content

​Content

​Content

​Content

customer.browser.screenHeight

Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. Mandatory for 3DS 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 3DS 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 3DS v2.

[\s\S]{1,5}

Conditional

customer.browser.userAgent

Exact content of the HTTP user-agent header. Mandatory for 3DS 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 3DS 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.

N2

Optional

customer.browser.deviceId

Value representing the customer browser device id.

AN32 [\s\S]{1,32}

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.* and shipping.customer.browser.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.

AN80 [\s\S]{1,80}

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.

AN30 [A-Za-z0-9]{1,30}

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

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

AN30 [A-Za-z0-9]{1,30}

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: LOWEST_COST, CARRIER_DESIGNATED_BY_CUSTOMER, ELECTRONIC_DELIVERY, GROUND, INTERNATIONAL, MILITARY, NEXT_DAY_OVERNIGHT, OTHER, STORE_PICKUP, SAME_DAY_SERVICE, TWO_DAY_SERVICE, THREE_DAY_SERVICE, PUDO, EXPEDITED

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

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

AN100 [\s\S]{1,100}

Optional

merchant.city

The merchant's city, phone number, email or url. 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

AN10 [A-Za-z0-9\-]{1,10}

Optional

merchant.state

The county, state or region of the merchant

AN50 [a-zA-Z0-9]{1,50}

Optional

merchant.country

The country of the merchant

A2 [A-Za-z]{2}

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

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].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].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].originalPrice

The cart item's price before discounts. The item's price is independent of the quantity.

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

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

Tokenization and Registration

As described in the Tokenization Guide there are two ways to store a customer's data on the system. 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 PrimeiroPay as well as when sending the payment over registration one-click payment Server-to-Server.

A5 true|false

Optional

Recurring

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

Parameter

Description

Format

Required

recurringType

Used to indicate the type of recurring payment.

  • INITIAL: The payment is the first of a series of payments. This first payment has to 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.

A20 INITIAL|REPEATED

Optional

recurring.numberOfInstallments

The number of installments the payment should be split into.

N3

Optional

Recurring Migration

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.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.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.v1.visa.requestorId

Merchant ID for 3D Secure version 1.0, assigned by Visa.

AN100 [\s\S]{100}

Optional

threeDSecure.v1.mastercard.requestorId

Merchant ID for 3D Secure version 1.0, assigned by Mastercard.

AN100 [\s\S]{100}

Optional

threeDSecure.v1.diners.requestorId

Merchant ID for 3D Secure version 1.0, assigned by Diners/Discover.

AN100 [\s\S]{100}

Optional

threeDSecure.v1.diners.password

Password for the Diners/Discover ProtectBuy Directory Server. Used for 3D Secure 1.0

AN100 [\s\S]{100}

Optional

threeDSecure.v1.amex.requestorId

Merchant ID for 3D Secure version 1.0, assigned by American Express.

AN100 [\s\S]{100}

Optional

threeDSecure.v1.jcb.requestorId

Merchant ID for 3D Secure version 1.0, assigned by JCB.

AN100 [\s\S]{100}

Optional

threeDSecure.v1.jcb.password

Password for the JCB J/Secure Directory Server. Used for 3D Secure 1.0

AN100 [\s\S]{100}

Optional

threeDSecure.v1.dankort.requestorId

Merchant ID for 3D Secure version 1.0, assigned by Dankort.

AN100 [\s\S]{100}

Optional

threeDSecure.v1.bcmc.requestorId

Merchant ID for 3D Secure version 1.0, assigned by Bancontact/Mistercash.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.visa.requestorId

Requestor ID for 3D Secure version 2, assigned by Visa.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.visa.requestorName

Requestor Name for 3D Secure version 2, assigned by Visa.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.mastercard.requestorId

Requestor ID for 3D Secure version 2, assigned by Mastercard.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.mastercard.requestorName

Requestor Name for 3D Secure version 2, assigned by Mastercard.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.amex.requestorId

Requestor ID for 3D Secure version 2, assigned by American Express.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.amex.requestorName

Requestor Name for 3D Secure version 2, assigned by American Express.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.diners.requestorId

Requestor ID for 3D Secure version 2, assigned by Diners/Discover.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.diners.requestorName

Requestor Name for 3D Secure version 2, assigned by Diners/Discover.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.jcb.requestorId

Requestor ID for 3D Secure version 2, assigned by JCB.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.jcb.requestorName

Requestor Name for 3D Secure version 2, assigned by JCB.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.cartebancaire.requestorId

Requestor ID for 3D Secure version 2, assigned by Carte Bancaire.

AN100 [\s\S]{100}

Optional

threeDSecure.v2.cartebancaire.requestorName

Requestor Name for 3D Secure version 2, 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 version 2, 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: 1.0.2 or 2.1.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 used for 3D Secure version 2.2 or higher.

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

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

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. Must be sent URL encoded.

AN2048 [\s\S]{6,2048}

Conditional

notificationUrl

This URL will receive the asynchronous notification where applicable. 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 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:

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

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

Giftcard

A giftcard allows you to send additional information for payments and risk checks that have a gift card.

Parameter

Description

Format

Required

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 Payment Jobs

The following parameters are additional parameters available for scheduling payment jobs

Parameter

Description

Format

Required

job.name

The name of the job to be scheduled

AN64 [\s\S]{1,64}

Optional

job.year

Here you can specify/limit which year(s) the job will run You can specify specific year, or comma separated years or * which means endless.

(\d{4})?(\,\d{4})*|\*

Optional

job.month

Here you can specify/limit which year(s) the job will run You can specify specific month, or comma separated months or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.dayOfMonth

Here you can specify/limit which day(s) the job will run You can specify specific day, or comma separated days or * which means endless. Note that you can't specify both dayOfMonth and dayOfWeek, only one should be specified

(\d{2})?(\,\d{2})*|\*

Optional

job.dayOfWeek

Here you can specify/limit which week day(s) the job will run You can specify specific day, or comma separated days or * which means endless. Note that you can't specify both dayOfMonth and dayOfWeek, only one should be specified

(\d)?(\,\d)*|\*

Optional

job.hour

Here you can specify/limit which week hour(s) the job will run You can specify specific hour, or comma separated hours or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.minute

Here you can specify/limit which week minute(s) the job will run You can specify specific minute, or comma separated minutes or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.second

Here you can specify/limit which week second(s) the job will run You can specify specific second, or comma separated minutes or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.startDate

Here you can specify starting at which date/time this job should be executed

yyyy-MM-dd HH:mm:ss

Optional

job.endDate

Here you can specify at which date/time this job should be ended

yyyy-MM-dd HH:mm:ss

Optional

job.noticeUnit

Here you can specify the date/time unit of noticeNumber

"YEAR"|"MONTH"|"WEEK"|"DAY"|"HOUR"|"MINUTE"|"SECOND"

Optional

job.noticeNumber

The notice to deschedule the job before until duration end

Number

Optional

job.noticeCallable

When the notice could be callable?

ANYTIME|DURATION_END

Optional

job.durationUnit

Here you can specify the date/time unit of durationNumber

"YEAR"|"MONTH"|"WEEK"|"DAY"|"HOUR"|"MINUTE"|"SECOND"

Optional

job.durationNumber

The minimum time/date of the duration of the job

Number

Optional

job.expression

You can specify a cron expression here that represents how often the job will run If you specify this parameter, then it will overrite (year,month,dayOfMonth,dayOfWeek,hour, minute and second) parameters values

See http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html

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

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

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

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

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

​Content

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)

​Content

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.

  • 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

Optional

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

Optional

standingInstruction.source

Indicating the type of subsequent payment transaction.

  • CIT: Cardholder initiated transaction.

  • MIT: Merchant initiated transaction.

CIT| MIT

Optional

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:

  • 'resultDetails.CardholderInitiatedTransactionID'

  • Or as one for the ConnectorTxIDs

  • The exact OPP response field is documented in the respective Connector integration sheet.

The ID must be included in all following MIT flagged transaction.

AN or N (No specific format- Depends on acquirer)

Optional

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.

​Content

​Content