Request Parameters

Request Parameters

General information

This page describes the request parameters for initiating the communication with the QENTA Checkout Server.

Please take the following information into consideration during integration into your online shop:

  • Please be aware to use the same upper and lower case writing of the parameter names and values as described.

  • As regards length restrictions, please note that we use UTF-8 for encoding, i.e. ASCII-characters require 1 byte, special characters like ö, ä, ü, ß, …​ require 2 bytes. If the maximum length is exceeded, a validation error occurs and the request is rejected. Since line breaks (' \n ', ' \r ' …​) are ignored, they can be removed before sending.

  • Some payment methods require additional request parameters or may have other particular requirements regarding request parameters. Please have a look at the Payment method specific documentation for more information about the use of these additional request parameters and particular parameters.

  • The parameter tables below include 3D Secure 2 parameters. For more information regarding 3D Secure 2, please visit the 3D Secure 2 page.

Some of the required or optional parameters (serviceUrl, confirmUrl and imageUrl) contain URLs which are used during the checkout process either to read content or to call that URL to return parameters to your online shop. There are some important technical requirements you have to consider for these URLs because they need to be accessible for your consumers and the QENTA Checkout Server over the Internet:

  • Please do not use any resources protected by htaccess (basic authentication) since no authentication data are provided when these URLs are called.

  • Please also note that no cookies are passed to these URLs.

  • Addresses from your private intranet and from the QENTA Payment CEE address range are not permitted. To get more detailed information about public and private IP address ranges have a look at https://www.iana.org or at Wikipedia. Private address ranges as defined by NIC are:

    • from 10.0.0.0 to 10.255.255.255

    • from 172.16.0.0 to 172.31.255.255

    • from 192.168.0.0 to 192.168.255.255

Restrictions for parameters

Please be aware that the QENTA Checkout Server has restrictions regarding the parameter names and values.

GET parameters

  • Max. numbers of parameters you are able to use is 1024.

  • Max. length of a parameter name must not exceed 64 characters.

  • Max. length of the value of a parameter must not exceed 2048 characters.

POST parameters

  • Max. numbers of parameters you are able to use is 12000.

  • Max. length of a parameter name must not exceed 64 characters.

  • Max. length of the value of a parameter must not exceed 65000 characters.

Required parameters

To initiate the payment process you have to set all required parameters to their corresponding values you need within your online shop. If one or more of these required parameters are missing you will get an error message.

QPAY Checkout Page and QMORE Checkout Seamless
Parameter Within fingerprint Data type Short description

customerId

Required

Alphanumeric with a fixed length of 7.

Unique ID assigned to each merchant by QENTA.

language

Required

Alphabetic with a fixed length of 2.

Language for displayed texts on payment page.

paymentType

Optional

Enumeration

Selected payment method of your consumer.

amount

Required

Amount

Amount of payment.

currency

Required

Alphabetic with a fixed length of 3 or numeric with a fixed length of 3.

Currency code of amount.

orderDescription

Required

Alphanumeric with a variable length of up to 255.

Unique description of the consumer’s order in a human readable form.

successUrl

Required

Alphanumeric with special characters.

URL of your online shop when payment process was successful.

cancelUrl

Optional

Alphanumeric with special characters.

URL of your online shop when payment process has been canceled.

failureUrl

Optional

Alphanumeric with special characters.

URL of your online shop when an error occurred within payment process.

serviceUrl

Optional

Alphanumeric with special characters and a variable length of up to 255.

URL of web page containing your contact information (imprint).

requestFingerprintOrder

Required

Alphanumeric with special characters.

Ordered list of parameters used for calculating the fingerprint.

requestFingerprint

Never

Alphanumeric with a fixed length of 128 for hash mechanism HMAC-SHA-512.

Computed fingerprint of the parameter values as given in the requestFingerprintOrder.

Additionally for QMORE Checkout Seamless
Parameter Within fingerprint Data type Short description

confirmUrl

Required

Alphanumeric with special characters.

URL of your online shop where QENTA sends a server-to-server confirmation.

consumerIpAddress

Required

Numeric with special characters.

IP address of consumer.

consumerUserAgent

Required

Alphanumeric with special characters.

User-agent of browser of consumer.

financialInstitution

Optional

Enumeration

Based on pre-selected payment method a sub-selection of financial institutions regarding the pre-selected payment method.

Optional parameters

Highly recommended

The following parameters for QPAY Checkout Page and QMORE Checkout Seamless are highly recommended, although they are optional, except for confirmUrl which is required for QMORE Checkout Seamless.

Parameter Within fingerprint Data type Short description

confirmUrl

Required if used.

Alphanumeric with special characters.

URL of your online shop where QENTA sends the confirmation to.
Necessary for receiving the payment process results independent from the behavior of your consumer.

customerStatement

Required if used.

Alphanumeric with variable length of up to 254 characters that may be restricted by specific payment methods.

Text displayed on bank statement issued to your consumer by the financial service provider.
Relevant information for your consumer to identify the payments made to your online shop.
Appearance of this text depends on payment method and financial service provider.

orderReference

Required if used.

Alphanumeric with a variable length up to 128 characters, but may differ for specific payment methods.

Unique order reference ID sent from merchant to financial institution.
Convenient to correlate the order numbers of your online shop with the effected payments.

pendingUrl

Optional

Alphanumeric with special characters.

URL of your online shop when result of payment process could not be determined yet.
Provides information to your consumer if payment is pending.

Additionally the consumer billing data, consumer shipping data data and the shopping basket data should be implemented from the beginning since these are required for certain payment methods.

QPAY Checkout Page and QMORE Checkout Seamless

You are able to use any combination of these optional parameters when initiating the payment process. These optional parameters enhance the functionality and usability for your consumer within the checkout process.

Parameter Within fingerprint Data type Short description

noScriptInfoUrl

Optional

Alphanumeric with special characters.

URL of your online shop where your information page regarding de-activated JavaScript resides.

orderNumber

Required if used.

Numeric with a variable length of up to 9.

Order number of payment.

windowName

Optional

Alphanumeric

Window name of browser window where payment page is opened.

duplicateRequestCheck

Required if used.

Boolean

Check for duplicate requests done by your consumer.

transactionIdentifier

Required if used.

Enumeration

Possible values are SINGLE (for one-off transactions) or INITIAL (for the first transaction of a series of recurring transactions).

cssUrl

Optional

URL

URL to a CSS file on your server to perform customizations.

isoTransactionType

Required if used.

Enumeration

It identifies the type of ISO transaction. The values are derived from ISO 8583. This field is required in some markets (e.g. for Merchants in Brazil). Otherwise optional. Accepted values: 01 = Goods/ Service Purchase. 03 = Check Acceptance. 10 = Account Funding. 11 = Quasi-Cash Transaction. 28 = Prepaid Activation and Load.

Additionally for QPAY Checkout Page
Parameter Within fingerprint Data type Short description

displayText

Optional

Alphanumeric with special characters.

Text displayed to your consumer during the payment process.

imageUrl

Optional

Alphanumeric with special characters.

URL of your online shop where your online shop logo is located.

backgroundColor

Optional

Alphanumeric.

Hex-coded RGB color-value as background color for the brand image containing the credit card logos, e.g. "f0f0f0".

financialInstitution

Optional

Enumeration

Based on pre-selected payment method a sub-selection of financial institutions regarding the pre-selected payment method.

Additionally for QMORE Checkout Seamless

Parameter Within fingerprint Data type Short description

orderIdent

Required if used.

Alphanumeric with special characters.

Unique ID of order which has to be the same as used for initiating the data storage.

storageId

Required if used.

Alphanumeric with a fixed length of 32.

Unique ID of data storage for a specific consumer.

Consumer data

The following parameters are used to pass on detailed information regarding your consumer. By default these parameters are optional, but for some specific payment methods like invoice or installment these parameters are required. For more information regarding the different payment methods have a look at the Payment method specific documentation.

Also note that the below mentioned data type descriptions and restrictions may differ depending on the relevant financial service provider.

Parameter Within fingerprint Data type Short description

consumerEmail

Required if used.

Alphanumeric with special characters and a variable length of up to 256.

E-mail address of consumer.

consumerBirthDate

Required if used.

Numeric with special characters and a fixed length of 10.

Birth date of consumer in the format YYYY-MM-DD.

consumerTaxIdentificationNumber

Required if used.

Alphanumeric with special characters and a variable length of up to 32.

Tax identification number of consumer.

consumerDriversLicenseNumber

Required if used.

Alphanumeric with special characters and a variable length of up to 32.

Drivers license number of consumer.

consumerDriversLicenseState

Required if used.

Alphabetic with a fixed length of 2 for US and CA, otherwise up to 40.

State which issued the drivers license of consumer.

consumerDriversLicenseCountry

Required if used.

Alphabetic with a fixed length of 2.

Country which issued the drivers license of consumer.

consumerMerchantCrmId

Required if used.

Alphanumeric with a variable length of up to 50 characters.

Unique ID identifying the consumer of your online shop, e.g. from your CRM system. The parameter must not be a human readable e-mail address. However, if an e-mail address is used it has to be hashed beforehand by the merchant.

consumerAuthenticationMethod

Required if used.

Enumeration

Type of consumer login in your shop. Accepted values: 01 = Guest checkout (i.e. the consumer is not logged in). 02 = Login to the consumer’s account in your shop with shop-own authentication credentials. 03 = Login with Federated ID. 04 = Login with card issuer credentials. 05 = Login with third-party authentication. 06 = Login with FIDO authenticator.

consumerAuthenticationTimestamp

Required if used.

timestamp

Date and time of the consumer login to your shop. Accepted format: YYYY-MM-DDThh:mm:ssZ. The values are derived from ISO 8601. For guest checkout, the timestamp is now.

consumerCardProvisionDate

Required if used.

Numeric with special characters and a fixed length of 10.

Date that the consumer’s card was added to their account in your shop for card-on-file payments (one-click checkout). Accepted format: DD.MM.YYYY. For all other types of checkout (e.g. guest checkout, regular checkout, the first transaction with one-click checkout), the date is now.

consumerCardProvisionAttemptsPastDay

Required if used.

Numeric with a variable length of up to 9.

Number of cards the consumer has attempted to add to their account in your shop for card-on-file payments (one-click checkout) in the past 24 hours.

consumerChallengeIndicator

Required if used.

Enumeration

Specifies whether this transaction shall be subject to Strong Customer Authentication (SCA). Accepted values: 01 = No preference. 02 = No challenge requested. 03 = Challenge requested. (3DS Requestor preference). 04 = Challenge requested (Mandate). If the element is not provided, the ACS will interpret this as 01 = No preference.

consumerSuspiciousActivity

Required if used.

Boolean

Suspicious activities by the consumer. Indicates if you have experienced suspicious activities by the consumer (including previous fraud).

consumerDeliveryTimeframe

Required if used.

Enumeration

Delivery time frame. Accepted values: 01 = Electronic Delivery. 02 = Same day shipping. 03 = Overnight shipping. 04 = Two-day or more shipping.

consumerPreorderDate

Required if used.

Numeric with special characters and a fixed length of 10.

The expected date that the item will be available for a pre-ordered purchase. Accepted format: DD.MM.YYYY.

consumerReorderItems

Required if used.

Enumeration

Indicates if the consumer is reordering previously purchased items. Accepted values: 01 = First time ordered. 02 = Reordered.

consumerAccountCreationDate

Required if used.

Numeric with special characters and a fixed length of 10.

Registration date of the consumer’s account in your shop. Accepted format: DD.MM.YYYY. For guest checkout, do not send this field.

consumerAccountUpdateDate

Required if used.

Numeric with special characters and a fixed length of 10.

Date that the consumer last made changes to their account in your shop, e.g. changes to billing and shipping address, new payment account, new email address. Accepted format: DD.MM.YYYY. For guest checkout, do not send this field.

consumerAccountPasswordChangeDate

Required if used.

Numeric with special characters and a fixed length of 10.

Date that the consumer last changed/reset their password in your shop. Accepted format: DD.MM.YYYY. For guest checkout, do not send this field.

consumerAccountPurchasesPastSixMonths

Required if used.

Numeric with a variable length of up to 9.

Number of successful orders by the consumer in your shop within the past six months.

consumerAccountTransactionsPastDay

Required if used.

Numeric with a variable length of up to 9.

Number of transactions (successful, failed, and canceled) that the consumer has attempted in the past 24 hours. Does not include merchant-initiated transactions.

consumerAccountTransactionsPastYear

Required if used.

Numeric with a variable length of up to 9.

Number of transactions (successful, failed, and canceled) that the consumer has attempted in the past year. Does not include merchant-initiated transactions.

Consumer Billing Data

Parameter Within fingerprint Data type Short description

consumerBillingFirstname

Required if used.

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 32 bytes.

First name of consumer.

consumerBillingLastname

Required if used.

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 32 bytes.

Last name of consumer.

consumerBillingAddress1

Required if used.

Alphanumeric with a variable length of up to 100 bytes.

Name of street and optionally the house number.

consumerBillingAddress2

Required if used.

Alphanumeric with a variable length of up to 100 bytes.

The house number if not already set in consumerBillingAddress1.

consumerBillingAddress3

Required if used.

Alphanumeric with a variable length of up to 100 bytes.

Further details regarding consumer’s address.

consumerBillingCity

Required if used.

Alphanumeric with a variable length of up to 32 bytes.

Billing city.

consumerBillingState

Required if used.

Alphabetic with a fixed length of 2.

Billing state.

consumerBillingCountry

Required if used.

Alphabetic with a fixed length of 2.

Billing country code (ISO 3166-1).

consumerBillingZipCode

Required if used.

Alphanumeric with a variable length of up to 12.

Billing zip code.

consumerBillingPhone

Required if used.

Alphanumeric with a variable length of up to 20.

Phone number of consumer.

consumerBillingMobilePhone

Required if used.

Alphanumeric with a variable length of up to 18.

Mobile phone number of consumer.

consumerBillingFax

Required if used.

Alphanumeric with a variable length of up to 20.

Fax number of consumer.

Consumer Shipping Data

Parameter Within fingerprint Data type Short description

consumerShippingFirstName

Required if used.

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 32 bytes.

First name of consumer.

consumerShippingLastName

Required if used.

First character has to be alphabetic, any other characters ASCII, with a variable length of up to 32 bytes.

Last name of consumer.

consumerShippingAddress1

Required if used.

Alphanumeric with a variable length of up to 100 bytes.

Name of street and optionally the house number.

consumerShippingAddress2

Required if used.

Alphanumeric with a variable length of up to 100 bytes.

The house number if not already set in consumerShippingAddress1.

consumerShippingCity

Required if used.

Alphanumeric with a variable length of up to 32 bytes.

Shipping city.

consumerShippingState

Required if used.

Alphabetic with a fixed length of 2.

Shipping state.

consumerShippingCountry

Required if used.

Alphabetic with a fixed length of 2.

Shipping country code (ISO 3166-1).

consumerShippingZipCode

Required if used.

Alphanumeric with a variable length of up to 12.

Shipping ZIP code.

consumerShippingPhone

Required if used.

Alphanumeric with a variable length of up to 20.

Shipping phone number.

consumerShippingFax

Required if used.

Alphanumeric with a variable length of up to 20.

Shipping fax number.

consumerShippingItemAvailability

Required if used.

Enumeration

Indicates whether consumer is placing an order for an item which is not yet available (released in the future) or which is currently available. Accepted values: 01 = Currently available 02 = Future availability

consumerShippingMethod

Required if used.

Enumeration

Shipping method chosen by the consumer. Use the shipping indicator value that applies most accurately to the shipping method. If the consumer checks out two or more items, use the shipping indicator value for physical goods. If all goods are digital goods, use the shipping indicator value that matches the most expensive item. Accepted values: home_delivery: Ship to consumer’s billing address. verified_address_delivery: Ship to another address which you know and have verified. other_address_delivery: Ship to an address that differs from the consumer’s billing address. store_pick_up: "Ship to Store" / Pick-up at local store (store address in shipping address fields). digital_goods: Digital goods (includes online services, electronic gift cards, and redemption codes). digital_tickets: Travel and event tickets, not shipped. other_verified: Other (e.g. gaming, digital services, e-media subscriptions).

consumerShippingAddressFirstUseDate

Required if used.

Numeric with special characters and a fixed length of 10.

Date that the consumer first used this shipping address in your shop. Accepted format: DD.MM.YYYY. For guest checkout, do not send this field.

Shopping basket data

The following parameters allow you to pass on detailed information about the content of your consumer’s shopping basket. By default these parameters are optional, but for some specific payment methods like invoice or installment these parameters are required. For more information regarding the different payment methods have a look at the Payment method specific documentation.

Although the following parameters are in general optional, either all parameters need to be set, except for basketItem(n)Description and basketItem(n)ImageUrl which remain optional, or none.

Shopping basket data

Parameter

Within fingerprint

Data type

Short description

basketItems

Required if used.

Numeric.

Number of items in shopping basket.

basketItem(n)ArticleNumber

Required if used.

Alphanumeric with special characters.

Unique ID of article n in shopping basket.

basketItem(n)Description

Required if used.

Alphanumeric with special characters.

Product description of article n in shopping basket.

basketItem(n)ImageUrl

Required if used.

Alphanumeric with special characters.

URL to an image of each item.

basketItem(n)Name

Required if used.

Alphanumeric with special characters.

Product name of article n in shopping basket.

basketItem(n)Quantity

Required if used.

Numeric

Items count of article n in shopping basket.

basketItem(n)UnitGrossAmount

Required if used.

Amount

Price per unit of article n in shopping basket with taxes.

basketItem(n)UnitNetAmount

Required if used.

Amount

Price per unit of article n in shopping basket without taxes.

basketItem(n)UnitTaxAmount

Required if used.

Amount

Tax amount per unit of article n in shopping basket.

basketItem(n)UnitTaxRate

Required if used.

Percentage of tax, e.g. 20 or 19.324. Up to 3 fractions.

Percentage of tax per unit of article n in shopping basket.

Since 21st April, 2016 the following parameters shall not be used since they result in technical restraints e.g. regarding the calculation of taxes. Existing implementations may still use these parameters, however, a complete replacement with the parameters mentioned above is recommended. Partial replacement leads to an error, therefore use all new parameters and remove all legacy parameters when replacing. If the legacy parameters are passed in parallel to the parameters described above, the data of the legacy parameters are ignored.

LEGACY Shopping basket data

Parameter

within fingerprint

Data type

Short description

basketAmount

Required if used.

Amount

Overall amount of shopping basket.

basketCurrency

Required if used.

Alphabetic with a fixed length of 3 or numeric with a fixed length of 3.

Code of currency based on ISO 4217.

basketItem(n)UnitPrice

Required if used.

Amount

Price per unit of article n in shopping basket without taxes.

basketItem(n)Tax

Required if used.

Amount

Tax amount of article n in shopping basket.

(n) …​ running number starting with 1 and up to the number of basket items

Please remember to also state possible shipping costs as a separate basketItem since otherwise the validation of the sum of the individual items and the total sum will fail. If different shipping costs apply to the different articles in the basket, the individual shipping costs must be stated as separate basketItem. In the below example the shipping costs are included as third (3) item.

Example of basket parameters for a shopping basket

The following simple example is intended to contribute to a better understanding of how to set the basket parameters.

The shopping basket of your consumer in your online shop contains the following items:

Quantity Description Number Price per unit Tax per unit

1

Product A1

A001

EUR 10,80

EUR 1,80

2

Product A2

A002

EUR 14,94

EUR 2,49

1

Shipping

S001

EUR 5,90

EUR 0,00

The parameters for describing the items in the shopping basket of your consumer would be:

Parameter name Value Description

basketItems

3

3 different products in shopping basket.

basketItem1ArticleNumber

A001

basketItem1Quantity

1

basketItem1Name

Product A1

basketItem1UnitGrossAmount

10,80

Gross price per item 1.

basketItem1UnitNetAmount

9,00

Net price per item 1.

basketItem1UnitTaxAmount

1,80

Tax for item 1.

basketItem1UnitTaxRate

20,000

Tax rate for item 1.

basketItem2ArticleNumber

A002

basketItem2Quantity

2

basketItem2Name

Product A2

basketItem2UnitGrossAmount

14,94

Gross price per item 2.

basketItem2UnitNetAmount

12,45

Net price per item 2.

basketItem2UnitTaxAmount

2,49

Tax for item 2.

basketItem2UnitTaxRate

20,000

Tax rate for item 2.

basketItem3ArticleNumber

S001

basketItem3Quantity

1

basketItem3Name

Shipping

basketItem3UnitGrossAmount

5,90

Gross price per item 3.

basketItem3UnitNetAmount

5,90

Net price per item 3.

basketItem3UnitTaxAmount

0,00

Tax for item 3.

basketItem3UnitTaxRate

0,000

Tax rate for item 3.

Feature-specific parameters

These optional parameters enhance the functionality and usability of the payment process regarding specific features and functions. To enable one or more of these parameters please contact our support teams.

QPAY Checkout Page and QMORE Checkout Seamless
Parameter Within fingerprint Data type Short description

autoDeposit

Required if used.

yes or no.

Enable automated debiting of payments.

confirmMail

Required if used.

Alphanumeric with special characters and a variable length of up to 127.

One payment confirmation mail address for the merchant.

shopId

Required if used.

Alphanumeric with a variable length of up to 16.

Unique ID of your online shop within your customer ID to enable various configurations of your online shop.

Additionally for QPAY Checkout Page

Parameter Within fingerprint Data type Short description

maxRetries

Required if used.

Numeric

Maximum number of payment attempts for the same order.

paymenttypeSortOrder

Optional

Enumeration / list.

Sort order of payment methods and sub-methods if your consumer uses SELECT as payment method.

Custom parameters

You have the possibility to add your own custom parameters when starting the payment process.

This feature can be used to transfer to your online shop specific parameters like a user session ID "through" the payment process.

These custom parameters may have any parameter names you want except of those parameter names which are reserved for request parameters and are specified as such in this documentation. Additionally, parameter names containing a dot (“.”) are replaced by parameter names in which the dot is replaced by an underline (“_”).

To prevent naming conflicts with possible future extensions of our QENTA solutions please use a prefix for your custom parameter names (e.g. “yourWebshopName_customValueXYZ”).

For your custom parameters you can use all possible values which are allowed to be sent as a POST request within an HTML form.

QPAY Checkout Page

All of your custom parameters are returned without any modification to your online shop when the URLs as defined in the parameters successUrl, cancelUrl, pendingUrl, failureUrl or confirmUrl are called when returning from the payment process to your online shop.

Additionally you have the possibility to add custom parameters directly as a query string to parameters containing URLs (like successUrl, cancelUrl, …​).

For example the value of the required parameter successUrl may have the form:

QMORE Checkout Seamless

All of your custom parameters are returned without modifications to your online shop via the confirmUrl. Please be aware that no parameters are returned to the successUrl when using QMORE Checkout Seamless.

Payment method specific parameters

For some payment methods you have to use specific parameters which are only necessary if these payment methods are enabled for your online shop. Please have a look at the Payment method specific documentation for detailed information about these required request parameters.

Deprecated request parameter

The following request parameter has become outdated and is no longer used by QENTA.

QPAY Checkout Page
Parameter Within fingerprint Data type History

layout

Optional

Enumeration of "desktop", "smartphone" or "tablet".

Only needed for non-responsive design.

Detailed description of required parameters

amount

With the parameter amount you need to specify the amount of the payment to be done by your consumer of your online shop. As a decimal separator only dot (“.”) or comma (“,”) are allowed values. Thousand separators are not permitted. The maximum number of decimal places depends on the selected currency within the currency parameter, e.g.:

Currency Decimal places

Euro

Maximum of 2 decimal places (100 Cent = 1 Euro).

US Dollar

Maximum of 2 decimal places (100 Cent = 1 US$).

Yen

No decimal places allowed.

Libyan Dinar

Maximum of 3 decimal places (1000 Dirham = 1 Dinar).

cancelUrl

The parameter cancelUrl has to contain the URL of your online shop where your consumer is forwarded when the payment process has been canceled by your consumer. On this page of your online shop you should inform your consumer about the cancelation of the payment process and offer possibilities to retry the payment attempt or get in contact with you.

cssUrl

The parameter cssUrl contains an URL to a CSS file stored on your server which is accessible from the Internet. The CSS file is used to adjust the responsive design of QPAY Checkout Page and QMORE Checkout Seamless.

currency

With the parameter currency you need to define the currency to be used for the payment in conjunction with the amount of the payment.

Please be aware that by default only EUR is enabled to be used as currency. If you would like to enable additional currencies for your online shop please contact our support teams.

The value of this parameter is based on ISO 4217 and can either be an alphabetic or numeric one. A short example of some currencies is listed below.

Alphabetic value Numeric value Currency

CHF

756

Swiss Franc

CZK

203

Czech Koruna

EUR

978

Euro

GBP

826

Pound Sterling

HUF

348

Hungarian Forint

PLN

985

Polish Zloty

USD

840

US Dollar

For a complete list of currencies consult Wikipedia or ISO Standards.

Please be aware that not all available payment methods support all currencies. To get detailed information regarding a specific payment method, please read the corresponding page.

customerId

With the parameter customerId you need to send the unique ID of the merchant using the QENTA Checkout Server.

For demo mode and for testing your integration in test mode use the relevant demo data and test data as described in QPAY Checkout Page and QMORE Checkout Seamless.

For production mode you will get your personal customerId in conjunction with your personal secret from our support teams.

failureUrl

With the parameter failureUrl you need to define the URL of your online shop where your consumer is forwarded when the payment process has failed for some reason. On this page of your online shop you should inform your consumer about the failure of the payment process and offer possibilities to retry the payment attempt or get in contact with you.

language

With the parameter language you need to define the language used for all messages of QPAY Checkout Page and QMORE Checkout Seamless that are displayed to the consumer of your online shop.

Please take into consideration that by default only English and German are activated. If you need additional languages please contact our support teams to enable the desired languages for your online shop.

If the language selected for your online shop is not supported by the respective financial service provider, the financial service provider decides which language is displayed to the consumer, e.g. default language, accept-language header.

The following languages are currently available:

Value Language

ar

Arabian

bs

Bosnian

bg

Bulgarian

zh

Chinese

hr

Croatian

cs

Czech

da

Danish

nl

Dutch

en

English

et

Estonian

fi

Finnish

fr

French

de

German

el

Greek

he

Hebrew

hi

Hindi

hu

Hungarian

it

Italian

ja

Japanese

ko

Korean

lv

Latvian

lt

Lithuanian

mk

Macedonian

no

Norwegian

pl

Polish

pt

Portuguese

ro

Romanian

ru

Russian

sr

Serbian

sk

Slovakian

sl

Slovenian

es

Spanish

sv

Swedish

tr

Turkish

uk

Ukrainian

orderDescription

With the parameter orderDescription you need to add a description of what your consumer paid for, i.e. a text cross-referencing the order made in the online shop, e.g. basket id, consumer id, e-mail, etc.

This text is not transmitted to any financial service provider and is therefore NEVER displayed on any consumer’s invoice or statement. The text contained in orderDescription is displayed in the QPC Payment Center.

If the optional request parameter displayText is not used, the orderDescription text will also be visible as consumer information in QPAY Checkout Page.

The value of this parameter must not contain any special characters or line breaks. In addition, no special HTML characters such as foreign characters, quotation marks (e.g. &auml or Ü) should be included as these could be converted by the browser itself. If such characters are included, our fingerprint computation is not identical with yours and the error message "Invalid fingerprint!" is displayed.

paymentType

With the parameter paymentType you need to define the value of the payment method the user selected in your online shop.

Please be aware that you can only use those payment methods you have purchased and enabled by QENTA. If you would like to offer additional payment methods within your online shop please contact our sales teams.

Value of parameter paymentType Payment method

SELECT

The consumer may select one of the activated payment methods directly in QPAY Checkout Page. Please note that SELECT is only available for QPAY Checkout Page.

CCARD

Credit Card, Maestro SecureCode

CCARD-MOTO

Credit Card - Mail Order and Telephone Order

EPS

eps-Überweisung

GIROPAY

giropay

IDL

iDEAL

INSTALLMENT

Installment: payolution

INVOICE

Invoice: payolution

PRZELEWY24

Przelewy24

PAYPAL

PayPal

PSC

paysafecard

SEPA-DD

SEPA Direct Debit

SOFORTUEBERWEISUNG

Sofort.

requestFingerprint

The parameter requestFingerprint has to contain your computed fingerprint based on the parameter values you define in the parameter requestFingerprintOrder.

This method is used for security reasons to verify that the parameters your online shop sends to the QENTA Checkout Server are valid and not compromised by someone else.

Please ensure that at least one of your parameters used for computing the fingerprint is unique to each order to prevent sending the same hash-value!

To authenticate all requests to the QENTA Checkout Server the HMAC-SHA-512 construction is used by combining the cryptographic hash function SHA-512 with the secret as the cryptographic key to hash the concatenated request parameter values in the order defined in the requestFingerprintOrder.

requestFingerprintOrder

The parameter requestFingerprintOrder has to contain an ordered list of all parameter names separated by comma the values of which are used to create the fingerprint.

You need to use all as required defined parameters for creating the fingerprint.

You can add the parameter names in any order you want, but you have to adjust the order of the parameter values you use while calculating the fingerprint accordingly.

An example of a possible value of this parameter can be:

secret,customerId,amount,currency,language,orderDescription,successUrl,requestFingerprintOrder

serviceUrl

The parameter serviceUrl is used to define the URL of a web page in your online shop which informs your consumer about the different possibilities to get in contact with you (imprint). Please do not use this URL to link to the shopping basket of your consumer!

If you do not use the optional parameter imageUrl, the serviceUrl is not used in the QPAY Checkout Page and your consumer has no possibility to access your service page in your online shop during the payment process.

Additionally some payment methods use this serviceUrl and require a properly set information page, therefore this parameter is also useful for QMORE Checkout Seamless.

This URL has to be accessible over the internet via port 80 (for http communication) or port 443 (for https communication) and may not be hosted on a local server which cannot be accessed by the QENTA Checkout Server.

successUrl

With the parameter successUrl you need to define the URL of your online shop where your consumer is forwarded when the payment process has been successfully completed by your consumer. On this page of your online shop you should inform your consumer about the success of the payment process.

Detailed description of optional parameters

backgroundColor

If you set a different background color for the HTML pages in your custom CSS for QPAY Checkout Page, you are able to also set the background color for the brand image containing the credit card logos. This can be done by using backgroundColor as an additional optional request parameter. The value for this parameter is a hex-coded RGB color-value for the color you are using as your background color, e.g. "f0f0f0".

confirmUrl

With the parameter confirmUrl you can define the URL of your online shop used by the QENTA Checkout Server to send to your online shop some return values containing the result of the payment process.

For the consumer of your online shop this URL is not a visible page. The URL is used as an entry-point for a server-to-server communication from the QENTA Checkout Server to your online shop to inform your system about the result of the payment.

For QPAY Checkout Page this parameter is optional because the same parameters and values are posted to successUrl, failureUrl, cancelUrl or pendingUrl.

For QMORE Checkout Seamless this parameter is required because no return parameters are sent to the successUrl.

We encourage you to use the confirmUrl in order to save the result of each payment process in your database for later use. Additionally if your consumer does not receive the page of the successUrl, the confirmUrl allows you to get informed about the result of the payment process anyway.

This URL has to be accessible over the internet via port 80 (for http communication) or port 443 (for https communication) and may not be hosted on a local server which cannot be accessed by the QENTA Checkout Server via the Internet. Also ensure that your firewall configurations allow to receive the confirmation sent via 212.183.46.16/28. Please note that for HTTPS communication only TLS can be used. Older protocols are not supported.

Optionally you have the possibility to receive an e-mail for each transaction regardless of the settings of the request parameters confirmUrl or confirmMail. To enable this feature please contact our sales teams.

Confirmation re-delivery attempts

By default, QENTA does not verify whether or not the confirmation was successfully received by your web server. If you wish to enable our feature allowing several re-delivery attempts, please contact our Support team or sales teams for setting the intervals for re-delivery attempts according to your requirements. The intervals are set in minutes (minimum is one minute) or hours (maximum are 99 hours). Please remember that only whole numbers may be used. If you have more than one online shop within one customerId, you have to decide for which shop you wish to enable this feature. During times of high load on the QENTA Checkout Server, a re-delivery attempt may start a bit delayed, however, it will never start before your defined interval.

To use this feature, the request parameter confirmUrl has to be sent. Optionally you may use the request parameter confirmMail to send confirmation mails individually per transaction.

In order to know whether or not a confirmation was successfully delivered, a certain string has to be returned by your web server to the QENTA Checkout Server. If the confirmation was successfully received, the response shall contain result="OK". If confirmation was not successfully received, the response shall contain both result="NOK" and a message which specifies the error. Since these error messages are logged, QENTA is able to carry out an error tracking based on these messages. Please use one of the following three possibilities to configure your response parameters:

Provided that the template mechanisms of the online shops permit to write HTML comments, the following content is possible for HTML comments and plain response: <QPAY-CONFIRMATION-RESPONSE result="OK|NOK" message="ans..255" /> e.g.:

  • Embedded as HTML comment:

    • <!--<QPAY-CONFIRMATION-RESPONSE result="OK" />--> for confirming the successful receipt of our confirmation.

    • <!--<QPAY-CONFIRMATION-RESPONSE result="NOK" message="Fingerprint validation failed." />--> for confirming the unsuccessful receipt of our confirmation.

or

  • Embedded as plain response:

    • <QPAY-CONFIRMATION-RESPONSE result="OK" /> for confirming the successful receipt of our confirmation.

    • <QPAY-CONFIRMATION-RESPONSE result="NOK" message="Session not found." /> for confirming the unsuccessful receipt of our confirmation.

or

  • As JSON response if header content type is application/JSON:

    • {"status":"OK","errorCodes":null,"QPAY-CONFIRMATION-RESPONSE":{"result": "OK"}} for confirming the successful receipt of our confirmation.

    • {"status":"NOK","errorCodes":12345,"QPAY-CONFIRMATION-RESPONSE":{"result": "NOK","message":"Session not found."}} for confirming the unsuccessful receipt of our confirmation.

If your web server is down for some reason or cannot be accessed by the QENTA Checkout Server, the ''confirmUrl'' cannot be delivered and no responses may be sent. In such cases, QENTA will continue to resend the confirmation until receiving the ''%%result="OK"%%'' or until the last re-delivery attempt was made.

In case QENTA has sent a confirmation and no response was received by the time the last re-delivery attempt was made, only one final information is sent to the given e-mail address. Please note that no further attempts to re-deliver the confirmation will be made by QENTA.

If the consumer in your online shop has terminated a session unexpectedly (e.g. closing the browser window) the first confirmation is sent automatically and no earlier than 30 minutes after the request was sent by QENTA.

customerStatement

With the parameter customerStatement you can define a text which is displayed on the bank statement issued to your consumer by the financial service provider.

Please note that the appearance of this text and also the allowed set of characters and the length of the text depend on the financial service provider.

displayText

With the parameter displayText you can define a text which is displayed during the payment process on the QPAY Checkout Page. If this parameter is not used, the required parameter [OrderDescription] will be used instead.

This text is not transmitted to any financial service provider and is therefore NEVER displayed on any consumer’s invoice or statement.

duplicateRequestCheck

You can use the parameter duplicateRequestCheck for checking if the same order has been unintentionally sent more than once by your consumer. This is useful to prevent processing of the same order more than once.

Your consumer may unintentionally resend the same order by pressing the reload-button of the browser because of problems with the internet connection.

For this check ensure that the required parameter orderDescription or any other customer parameter used in the fingerprint calculation is different for each order to prevent a false positive detection of duplicate requests. Since for each request a hash of all parameter values is sent, i.e. the fingerprint, QENTA can easily detect any identical request that has been sent in the last 30 minutes.

If you want QENTA to check for duplicate requests, set the value of this parameter to “yes”. Otherwise please do not send this parameter.

financialInstitution

You can use the parameter financialInstitution in conjunction with the parameter paymentType, when a specific payment method is selected by your consumer in your online shop. For some payment methods, the parameter financialInstitution is required for QMORE Checkout Seamless and optional for QPAY Checkout Page.

You can define one or more financial institutions which you want to offer to your consumer based on the selected payment method. The value is a comma-separated list of shortcuts which are described in the table below. The individual brands may be listed in any order within the parameter.

Possible examples for this parameter in conjunction with the payment method CCARD are:

  • Allow all brands, force 3-D Secure for brands that support 3-D Secure:

    • financialInstitution=amexsafekey,Diners,J/Secure,Discover,MCSC,Maestro,VbV

  • Limit to American Express SafeKey, Mastercard and Visa 3-D Secure:

    • financialInstitution=amexsafekey,MCSC,VbV

  • Limit to Mastercard and Visa non-3-D Secure:

    • financialInstitution=MC,Visa

  • Limit to Amex and Diners only:

    • financialInstitution=Amex,Diners

  • Limit to Mastercard and Visa 3-D Secure and non-3-D Secure:

    • financialInstitution=MCSC,MC,VbV,Visa

Please be aware that you may only use those brands that are defined in your merchant configuration. If you want to use all of your configured brands, it is not necessary to send this parameter at all. Should you wish to add further brands, please contact your sales contact person.

Payment methods EPS and IDL only allow one value, while other payment methods like Credit Cards allow a comma-separated list of values.

Values of financialInstitution by paymentType

paymentType CCARD
Possible value(s) of financialInstitution Description

MCSC

Mastercard ID Check

Maestro

Maestro SecureCode

Visa

Visa

VbV

Visa Secure

Amex

American Express

amexsafekey

American Express SafeKey

Diners

Diners Club

Discover

Discover

JCB

JCB

J/Secure

J/Secure™

UATP

Universal Airline Travel Plan

paymentType EPS
Possible value(s) of financialInstitution Description

ARZ,AAB

Austrian Anadi Bank AG

ARZ,MB

Marchfelder Bank

ARZ,BAF

Österreichische Ärzte- und Apothekerbank

BA-CA

Bank Austria

ARZ,BCS

Bankhaus Carl Spängler & Co. AG

ARZ,BSS

Bankhaus Schelhammer & Schattera AG

Bawag,BG

BAWAG P.S.K. AG

ARZ,BKS

BKS Bank AG

ARZ,BKB

Brüll Kallmus Bank AG

ARZ,BTV

BTV VIER LÄNDER BANK

ARZ,CBGG

Capital Bank Grawe Gruppe AG

ARZ,DB

Dolomitenbank

Bawag,EB

Easybank AG

Spardat,EBS

Erste Bank und Sparkassen

ARZ,HAA

Hypo Alpe-Adria-Bank International AG

ARZ,VLH

Hypo Vorarlberg Bank AG

ARZ,NLH

HYPO NOE LB für Niederösterreich u. Wien

Hypo-Racon,O

Hypo Oberösterreich

Hypo-Racon,S

Hypo Salzburg

Hypo-Racon,St

Hypo Steiermark

ARZ,HTB

Hypo Tirol Bank AG

BB-Racon

Bank Burgenland

ARZ,OB

Oberbank AG

Racon

Raiffeisen Bankengruppe Österreich

ARZ,SB

Schoellerbank AG

Bawag,SBW

Sparda Bank Wien

ARZ,VB

Volksbank Gruppe

ARZ,VKB

Volkskreditbank AG

ARZ,VRB

VR-Bank Braunau

EPS-SO

EPS SELECT OPTION

paymentType GIROPAY
Possible value(s) of financialInstitution Description

GIROPAY

giropay

paymentType IDL
Possible value(s) of financialInstitution Description

ABNAMROBANK

ABN AMRO Bank

ASNBANK

ASN Bank

BUNQ

Bunq Bank

INGBANK

ING

KNAB

Knab

RABOBANK

Rabobank

SNSBANK

SNS Bank

REGIOBANK

Regio Bank

TRIODOSBANK

Triodos Bank

VANLANSCHOT

Van Lanschot Bankiers

paymentType INVOICE
Possible value(s) of financialInstitution Description

payolution

Invoice by payolution

paymentType INSTALLMENT
Possible value(s) of financialInstitution Description

payolution

Installment by payolution

paymentType PAYPAL
Possible value(s) of financialInstitution Description

PAYPAL

PayPal

paymentType PRZELEWY24
Possible value(s) of financialInstitution Description

Przelewy24

Przelewy24

paymentType SEPA-DD
Possible value(s) of financialInstitution Description

SEPA-DD

SEPA Direct Debit

paymentType SOFORTUEBERWEISUNG
Possible value(s) of financialInstitution Description

SOFORTUEBERWEISUNG

Sofort.

imageUrl

With the parameter imageUrl you can define the URL to an image on your web server. This image will be displayed during the payment process in QPAY Checkout Page.

Please be aware that the image size should have a width of 95 pixel and a height of 65 pixel and the supported image formats are gif, jpg and png (recommended).

For security reasons we do not accept .svg images provided by the customer. Please use .png instead.

If you are using the parameter imageUrl please be aware that it is necessary that there is really an image available within the given image URL. Otherwise the loading of QPAY Checkout Page will be delayed until a time-out for the missing image occurs. This would have no impact on the functionality of QPAY Checkout Page, but the consumer of your online shop has then to wait longer till the payment process really starts.

If you do not use the imageUrl please be also aware that the required parameter serviceUrl will not be used. Otherwise the image will be encapsulated by a link to the serviceUrl, so that the consumer can click on the image to view the HTML page available at the serviceUrl.

This URL has to be accessible over the internet https:// and must be accessible by the QENTA Checkout Servers.

noScriptInfoURL

With the parameter noScriptInfoURL you can define the URL to an information page of your online shop which is displayed to your consumer if the web browser of your consumer has JavaScript disabled.

On this information page within your online shop you can inform your consumer of the requirement to enable JavaScript and a guide how to do this in the web browser.

orderIdent

With the parameter orderIdent you can define a unique reference to a specific order of a specific consumer within your online shop. This orderIdent is used within the QENTA data storage together with the customerId, shopId and storageId that only you are able to access the specific session of the QENTA data storage.

Typically when gathering payment related data of your consumer there may be no unique order number available so you could use the ID of the shopping basket to get a unique value.

Please be aware that the value of the orderIdent has to be unique for each order of your consumer.

You have to use the same value of the orderIdent for initializing the QENTA data storage and for initiating the payment process.

orderReference

With the parameter orderReference you can define a unique transaction ID which will be forwarded to the financial institution.

Please be aware that the set of allowed characters and the allowed maximum length depends on the payment methods and the corresponding financial service providers. You can find more details regarding the constraints of the values within Integration of specific payment methods.

pendingUrl

With the parameter pendingUrl you can define the URL of your online shop where your consumer is forwarded when the payment process could not determine a result yet. On this page of your online shop you should inform your consumer about the pending situation of the payment process.

When using the optional parameter pendingUrl, the use of the parameter confirmUrl is mandatory.

In such combination with the parameter confirmUrl you will receive the result of the payment process at a later time. Depending on the payment method this can take up to 14 calendar days.

The pendingUrl is an optional request parameter for backward compatibility to existing online shops, but we strongly encourage you to use this parameter for handling asynchronous payment methods or payment methods which may have sometimes a delay in returning a final state of a transaction.

Please be aware that the state "pending" is only used if this parameter is set in combination with the parameter confirmUrl. If you do not use this parameter you will get a "failure" instead of a "pending" state.

When the QENTA Checkout Server receives a final state from the corresponding financial service provider, we will send this information to the confirmUrl, so that you are aware of the final state of the "pending payment".

Below you find a list of payment methods including relevant information whether the pendingUrl is required, recommended or not needed.

paymentType Required Recommended Not needed

CCARD

EPS

GIROPAY

IDL

INSTALLMENT

INVOICE

PRZELEWY24

PAYPAL

PSC

SEPA-DD

SOFORTUEBERWEISUNG

storageId

The parameter storageId is the unique ID to the QENTA data storage of a specific consumer within a specific payment process. The storageId is valid for 30 minutes after the latest use of an intitialization, store or read operation on that data storage.

Please be aware that a storageId gets invalid after a successful initiation of the payment process.

transactionIdentifier

With the parameter transactionIdentifier you can define whether a transaction is a single (one-off) transaction or an initial transaction followed by many subsequent ones (e.g. for subscription models).

Two values may be used for this parameter - SINGLE for one-off transactions and INITIAL for the first transaction of a series of recurring payments.

  • If the parameter transactionIdentifier is not used, the value set in the merchant configuration is used.

  • If the parameter transactionIdentifier is used, the configuration settings are overwritten correspondingly.

From the consumer’s point of view, when purchasing products with recurring payments in your online shop, the parameter transactionIdentifier is used with value INITIAL. This enables you to use this initial transaction as a source for further transactions via the back-end operation recurPayment.

Especially for payment methods PayPal and SEPA Direct Debit it is required to distinguish between a single transaction or the first transaction with subsequent transactions based on the first one. The reason is that your consumer has to confirm that you are allowed to start additional transactions based on this first transaction.

Please note that the back-end operation recurPayment may only be carried out if the transactionIdentifier value INITIAL is used. Also remember that for using the value INITIAL for subsequent recurring transactions you need to obtain additional approval from your financial service provider, e.g. for PayPal. After receiving approval please contact our support teams to enable this feature.

Currently, the transactionIdentifier may be used for payment methods PayPal and SEPA Direct Debit. Therefore you need to restrict the parameter paymentType to these two types for initializing recurring transactions.

SINGLE

Standard singular transaction for which authorization is given once by the consumer to collect only one transaction, i.e. this authorization cannot be used for any subsequent transactions.

INITIAL

First transaction of a series of subsequent recurring transactions, i.e. for executing subscription models.

windowName

With the parameter windowName you can define the name of the pop-up window or iframe where QPAY Checkout Page or, in general, an additional payment window is opened.

This parameter is required if you offer payment methods which are opening an additional pop-up window like eps-Überweisung or PayPal. It ensures a proper return to the checkout process after that payment method specific pop-up window is closed.

Please be aware to comply to the following list of rules regarding the window name:

  • It must not contain any whitespace characters.

  • It must consist only of letters and numbers and the first character has to be a letter.

  • Uppercase and lowercase letters are permitted.

  • A distinction is made between uppercase and lowercase letters.

  • It must not contain any special or foreign characters.

  • The only permitted special character is the underscore ("_").

  • The window name must not be identical to a reserved word in JavaScript (see JavaScript reserved words).

Please be aware that opening QPAY Checkout Page or QMORE Checkout Seamless within a pop-up window may cause problems to your consumers if they have enabled a pop-up blocker within their browsers. Additionally pop-up blockers are getting more and more a standard feature of browsers and may be activated by default.

Additionally, for mobile devices like tablets or smartphones, please consider the following technical constraints and usability issues:

  • Iframes may result in a poor usability on touch devices, especially if your consumer needs to scroll within the content of the iframe.

  • Pop-up windows are not supported by all operating systems or mobile browsers, instead as a fallback the browser decides to open a new tab instead of a pop-up window. This may cause possible flaws within the user experience during the payment process on the mobile device.

  • If you are using a native web view, it is not possible to open a pop-up window out-of-the-box within the native app.

Detailed description of feature-specific parameters

autoDeposit

After a consumer has successfully completed a payment in your online shop, this payment - depending on the payment method - is only approved (authorized) and not yet deposited (captured).

In order to receive the amount from your financial service provider, a day-end closing has to be performed of all deposited payments.

Not deposited (uncaptured) approvals will expire after 7-14 calendar days. The exact deadline depends on the regulations provided by each financial service provider. After exceeding the individual deadline these payments can no longer be submitted or received.

In general, a day-end closing is performed automatically by your acquirers at defined times.

For SIX Payment Service and DC Bank a regular day-end closing of all deposited payments has to be performed manually by you in order to receive the approved (authorized) amounts.

To prevent the expiration of such uncaptured payments you may use the request parameter autoDeposit which enables an automated deposit and day-end closing of payments.

If you wish to enable this feature, please contact our Support team or sales teams and set the value of this parameter to yes

confirmMail

With the parameter confirmMail you can define one (exactly one) e-mail address of the merchant for receiving payment details regarding the orders of your consumers in the online shop. This e-mail may contain information about payment state, order number, payment method, payment amount and payment currency.

If you need to send the confirmation e-mail to multiple receivers please use an alias e-mail or a special rule for further distribution within your e-mail system.

If you do not use the optional parameter confirmUrl you will get an confirmation e-mail to the e-mail address given in this parameter for each payment made by your consumers.

If you use the optional parameter confirmUrl together with this parameter, you will only get a confirmation e-mail when an error occurred in the communication between QENTA and your web server. This ensures that even if we could not automatically inform your system about the result of the payment process you will get a confirmation notification by e-mail.

Optionally you have the possibility to get an e-mail for each transaction regardless of the setting of the parameters confirmUrl or confirmMail. To enable this feature please contact our sales teams.

Four different payment states may be reported depending on the result of the payment process:

SUCCESS

The payment has been successfully finished by the consumer.

CANCEL

The payment process has been canceled by the consumer and has not been successfully finished.

FAILURE

A problem occurred during the payment process and the payment has not been successfully finished.

PENDING

The payment is in progress. At this state we cannot inform about success or failure of this payment.

Depending on the returned payment state you need to inform your consumer and take appropiate actions.

Confirmation e-mail examples

The following four confirmation e-mail examples are used for demonstration purposes only and display the result of QPAY Checkout Page based on the actions taken by the consumer during the payment process:

maxRetries

You can use the parameter maxRetries for defining the maximum number of payment attempts regarding a unique order.

The value of this parameter is of type integer which can be a negative value, zero or a positive value:

Value Behavior

less than 0

No restriction regarding the number of retries a consumer can do.

exact 0

No retry is possible for your consumer. If an error occurs the consumer will be redirected to the failureUrl.

greater than 0

Maximum number of retries your consumer can do before redirecting to the failureUrl.

The following situations are not considered as errors in terms of maxRetries:

  • Missing parameter (e.g. an empty input field).

  • Incorrect length (e.g. a miss-typed credit card number).

  • Incorrect format (e.g. spaces or letters within the credit card number).

  • Configuration errors within QPAY Checkout Page, QMORE Checkout Seamless or the financial service provider.

  • Communication error within QPAY Checkout Page, QMORE Checkout Seamless or the financial service provider.

orderNumber

With the parameter orderNumber you can define a unique ID for the order. If the value of this parameter is set it is not possible that your consumer uses that order number a second time, even if your consumer could not successfully finalize the payment process. Therefore this parameter can only be used if the parameter maxRetries is set to 0.

paymenttypeSortOrder

This parameter enables you to define the sort order of all displayed payment methods and their corresponding sub-methods if paymentType is set to SELECT.

Additionally by using this parameter dependent of the country of your consumer you are able to offer a country-specific sort order of your payment methods. E.g. you are able to offer credit card in Austria, Sofort. in Germany and iDEAL in Netherland as the top-most payment method.

You can set the sort order of your payment methods by using a comma-separated list of payment methods as defined within the parameter [PaymentType].

For payment methods which are supporting sub-methods you can also add them to the comma-separated list. You can find all available sub-methods within the description of the parameter financialInstitution.

Example of a possible value for this parameter: EPS,ARZ|VB,PAYPAL,ABNAMROBANK,VANLANSCHOT,REGIOBANK,GIROPAY

Here "EPS-Überweisung" is the top-most payment method and its first sub-method is "Die österreichischen Volksbanken" followed by the remaining sub-method of EPS. The next payment method is "PayPal", followed by "iDEAL" with sub-method "ABN AMRO Bank", "Van Lanschot Bank" and "SNS Regio Bank". After iDEAL GiroPay is displayed, followed by all other payment methods configured for your online shop.

riskConfigAlias

Using this parameter you can select a specific predefined FPS risk rule.

If you have enabled the QENTA Fraud Prevention Suite (FPS), specific risk rules can be defined for your online shop. For each payment process a rule can be selected with this parameter. Based on the result of the selected rule your consumer will or will not be required to enter the 3-D Secure code. Requiring the 3-D Secure code increases the security for you.

riskSuppress

This parameter enables you to suppress the usage of the QENTA Fraud Prevention Suite (FPS) for the current transaction. Typically this is done when the merchant already knows the consumer as a "trustful" consumer and a risk check is therefore not required.

If you want to disable the risk check you are able to use one of the boolean values for YES.

If you explicit want to enable the risk check for the current transaction you may either not use this parameter or set one of the boolean values for NO.

shopId

With the parameter shopId you can define the unique identifier for your online shop within your customerId. This is used if you have multiple online shops or one online shop with multiple configurations within one customerId.

For example the shopId can be used to have different configurations of your payment methods within one customerId.