Optional Parameters

Optional Parameters

Highly Recommended

Table 1. Highly Recommended Optional Parameters
Parameter Within fingerprint Data type Description

confirmUrl

Required if used

Alphanumeric with special characters

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

customerStatement

Required if used

Alphanumeric with special characters, up to 254 characters

Text displayed on bank statement issued to your consumer by the financial service provider.

orderReference

Required if used

Alphanumeric with special characters, up to 128 characters

Unique order reference ID sent from merchant to financial institution. Correlate the order numbers of your online shop with the affected payments.

pendingUrl

Optional

Alphanumeric with special characters

URL of your online shop when the result of the payment process could not be determined yet.

The consumer billing data, consumer shipping data, and shopping basket data should be implemented from the beginning since these are required for certain payment methods.
Table 2. Optional Parameters
Parameter Within fingerprint Data type Description

noScriptInfoUrl

Optional

Alphanumeric with special characters

URL of your online shop where your information page regarding deactivated JavaScript resides

orderNumber

Required if used

Numeric, 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 and 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.

Table 3. Additionally for QPAY Checkout Page
Parameter Within fingerprint Data type 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 code RGB color value as background color for the brand image containing the credit card logos.

financialInstitution

Optional

Enumeration

Sub-selection of financial institutions regarding the pre-selected payment method.

Table 4. Additionally for QMORE Checkout Seamless
Parameter Within fingerprint Data type 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.

Parameters orderIdent and storageID become mandatory if data storage is used.

Consumer Data

These parameters are used to pass on detailed information to your consumer and some specific payment methods are required.

Table 5. Optional Parameters For Consumers
Parameter Within fingerprint Data type Description

consumerEmail

Required if used

Alphanumeric with special characters, up to 256 characters

E-mail address of the consumer.

consumerBirthDate

Required if used

Numeric with special characters, fixed-length 10

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

consumerTaxiIdentificationNumber

Required if used

Alphanumeric with special characters, up to 32 characters

Tax identification number of consumer.

consumerDriversLicenseNumber

Required if used

Alphanumeric with special characters, up to 32 characters

Drivers license number of consumer.

consumerDriversLicenseState

Required if used

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

State which issued the driver’s license of the consumer.

consumerDriversLicenseCountry

Required if used

Alphabetic, fixed length of 2 characters

Country which issued the drivers license of consumer.

consumerMerchantCrmId

Required if used

Alphanumeric, up to 50 characters

Unique ID identifying the consumer of your online shop. The parameter must not be a human-readable e-mail address.

consumerAuthenticationMethod

Required if used

Enumeration

Type of consumer login in your shop. Accepted values:
01 = Guest checkout
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.
For guest checkout, the timestamp is now.

consumerCardProvisionDate

Required if used

Numeric with special characters, fixed length of 10

Date that the consumer’s card was added to their account in your shop for card-on-file payments. Accepted format: DD.MM.YYYY.
For all other types of checkout, the date is now.

consumerCardProvisionAttemptsPastDay

Required if used

Numeric, up to 9 characters

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

consumerChallengeIndicator

Required if used

Enumeration

Specifies whether 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 it as 01 = No preference.

consumerSuspiciousActivity

Required if used

Boolean

Indicates if you have experienced suspicious activities by the consumer.

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, 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, fixed length of 10

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

consumerAccountUpdateDate

Required if used

Numeric with special characters, fixed length of 10

Date that the consumer last made changes to their account in your shop.
Accepted format: DD.MM.YYYY.
For guest checkout, don’t 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, don’t send this field.

consumerAccountPurchasesPastSixMonths

Required if used

Numeric, up to 9 characters

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

consumerAccountTransactionsPastDay

Required if used

Numeric, up to 9 characters

Number of transactions that the consumer has attempted in the past 24 hours. Does not include merchant-initiated transactions.

consumerAccountTransactionsPastYear

Required if used

Numeric, up to 9 characters

Number of transactions that the consumer has attempted in the past year. Does not include merchant-initiated transactions.

Consumer Billing Data

Table 6. Consumer Billing Data
Parameter Within fingerprint Data type Description

consumerBillingFirstname

Required if used

First character has to be alphabetic, any other characters ASCII, up to 30 bytes

First name of consumer.

consumerBillingLastname

Required if used

First character has to be alphabetic, any other characters ASCII, up to 30 bytes

Last name of consumer.

consumerBillingAddress1

Required if used

Alphanumeric, up to 100 bytes

Name of the street and optionally the house number.

consumerBillingAddress2

Required if used

Alphanumeric, up to 100 bytes

The house number if not already set in consumerBillingAddress1.

consumerBillingAddress3

Required if used

Alphanumeric, up to 100 bytes

Further details regarding consumer’s address.

consumerBillingCity

Required if used

Alphanumeric, up to 32 bytes

Billing city

consumerBillingState

Required if used

If the consumerBillingCountry is US or CA-Alphabetic, fixed 2 characters and can’t be empty. For all other country codes-Alphabetic, the max length is 40 characters and there is no minimum length.

Billing state

consumerBillingCountry

Required if used

Alphabetic, fixed 2 characters

Billing country code ISO 3166-1.

consumerBillingZipCode

Required if used

Alphanumeric, up to 12 characters

Billing zip code.

consumerBillingPhone

Required if used

Alphanumeric, up to 20 characters

Phone number of consumer.

consumerBillingMobilePhone

Required if used

Alphanumeric, up to 18 characters

Mobile phone number of consumer.

consumerBillingFax

Required if used

Alphanumeric, up to 20 characters

Fax number of consumer.

Consumer Shipping Data

Table 7. Consumer Shipping Data
Parameter Within fingerprint Data type Description

consumerShippingFirstName

Required if used

First character has to be alphabetic, any other characters ASCII, up to 30 bytes

First name of the consumer.

consumerShippingLastName

Required if used

First character has to be alphabetic, any other characters ASCII, up to 30 bytes

Last name of the consumer.

consumerShippingAddress1

Required if used

Alphanumeric, up to 100 bytes

Name of the street and optionally the house number.

consumerShippingAddress2

Required if used

Alphanumeric, up to 100 bytes

The house number if not already set in consumerShippingAddress1.

consumerShippingCity

Required if used

Alphanumeric, up to 32 bytes

Shipping city.

consumerShippingState

Required if used

If the consumerShippingCountry is US or CA-Alphabetic, fixed 2 characters and can’t be empty. For all other country codes-Alphabetic, the max length is 40 characters and there is no minimum length.

Shipping state.

consumerShippingCountry

Required if used

Alphabetic, fixed 2 characters

Shipping country code ISO 3166-1.

consumerShippingZipCode

Required if used

Alphanumeric, up to 12

Shipping ZIP code.

consumerShippingPhone

Required if used

Alphanumeric, up to 20

Shipping phone number.

consumerShippingFax

Required if used

Alphanumeric, 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 or which is currently available.
Accepted values:
01 = Currently available
02 = Future availability.

consumerShippingMethod

Required if used

Enumeration

Shipping method chosen by the consumer. Accepted values:
home_delivery: Ship to consumer’s billing address
verified_address_delivery: Ship to verified addres
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
digital_goods: e.g. gift cards, digital_tickets: Travel and event tickets, not shipped
other_verified: Other e-media subscriptions.

consumerShippingAddressFirstUseDate

Required if used

Numeric with special characters, fixed 10

Date that the consumer first used this shipping address in your shop.
Accepted format: DD.MM.YYYY.

Shopping Basket Data

Parameters that allow you to pass on detailed information about the content of your consumer’s shopping basket. By default are optional, but for some specific payment methods like invoice or installment are required.

Although the following parameters are optional, all parameters need to be set, except for basketItem(n)Description and basketItem(n)ImageUrl which remain optional.
Table 8. Shopping Basket Data
Parameter Within fingerprint Data type Description

basketItems

Required if used

Numeric

Number of items in the 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 the 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 the shopping basket.

basketItem(n)Quantity

Required if used

Numeric

Items count of article n in the shopping basket.

basketItem(n)UnitGrossAmount

Required if used

Amount

Price per unit of article n in the 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.

Set possible shipping costs as a separate basketItem; 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.

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

Table 9. Shopping Basket of Your Consumer
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

3

Shipping

S001

EUR 5,90

EUR 0,0

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

Table 10. Parameters for describing the items
Parameter 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,0

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 these parameters contact our integration specialists.

Table 11. QPAY Checkout Page and QMORE Checkout Seamless
Parameter Within fingerprint Data type Description

autoDeposit

Required if used.

yes or no

Enable automated debiting of payments.

confirmMail

Required if used.

Alphanumeric with special characters, up to 127.

One payment confirmation mail address for the merchant.

shopId

Required if used.

Alphanumeric, up to 16.

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

Display or edit consumer data

This feature allows your consumer to enter his shipping or billing information after opening the payment link. Contact our integration specialists to enable the feature.

Table 12. Basket Items
Parameter Within fingerprint Data type Description

displayBasketData

Optional

Enumeration

Y- Display Basket Items on Checkout Page.

N- Don’t display Basket Items.

Provide basket items to init or via payByLink. Items or amounts can’t be changed by the consumer afterwards.
Table 13. Shipping Data
Parameter Within fingerprint Data type Description

displayShippingData

Optional

Enumeration

E: Editable. Let consumer edit Shipping Data.

Y: Display only. (If provided by merchant)

N: Don’t display consumer’s Shipping Data.

If set to Y the merchant must provide the Shipping Data to display during init or via PayByLink.
Table 14. Billing Data
Parameter Within fingerprint Data type Description

displayBillingData

Optional

Enumeration

E: Editable. Let consumer edit Billing Data.

Y: Display only. (If provided by merchant)

N: Don’t show consumer’s Billing Data.

If no billing data is sent to init but shipping Data is, then consumer can choose to use shipping data as billing data.

If any of displayBasket, displayBillingData, displayShippingData is set to Y or E you receive an additional return parameter during confirmation that contains the consumer’s information.

Table 15. Additionally for QPAY Checkout Page
Parameter Within fingerprint Data type 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.

Restrictions for Payment Methods

Table 16. Restrictions of parameter customerStatement
Acquirer Brand Data type

Afterpay

AfterPay

ASCII, up to 254 characters

American Express

American Express

ASCII, up to 254 characters

B+S

Mastercard, Visa

ASCII, up to 254 characters

card complete

Maestro SecureCode, Mastercard, Visa

Alphanumeric, up to 25 characters.

ConCardis

Maestro SecureCode, Mastercard, Visa

ASCII, up to 254 characters.

b4payment

b4payment

ASCII, up to 254 characters.

DC Bank

Diners Club

ASCII, up to 254 characters

EPS

EPS

ASCII, up to 254 characters.

Giropay

Giropay

ASCII, up to 254 characters.

Hobex

Maestro SecureCode, Mastercard, Visa

customerStatement is not used and the name of the merchant is always displayed on the consumer’s bank statement.

Hobex

SEPA Direct Debit

ASCII, up to 254 characters.

Klarna

Sofort

ASCII, up to 254 characters.

PayPal

PayPal

ASCII, up to 254 characters.

Przelewy24

Przelewy24

ASCII, up to 25 characters.

paysafecard

paysafecard

ASCII, up to 254 characters.

payolution

payolution

ASCII, up to 254 characters.

SIX Pay

Maestro SecureCode, Mastercard, Visa

ASCII, up to 254 characters

SIX Payment Services

Maestro SecureCode, Mastercard, Visa

ASCII, up to 254 characters

Sofort

Sofort

ASCII, up to 254 characters

Worldline

Maestro SecureCode, Mastercard, Visa

Alphanumeric with special characters, up to 22 characters

Table 17. Restrictions for Parameters orderReference and merchantReference:
Acquirer Brand Data type

Afterpay

AfterPay

ASCII, up to 254 characters

American Express

American Express

Not supported

B+S

Mastercard, Visa

Not supported

ConCardis

Mastercard, Visa

Not supported

card complete

Maestro SecureCode, Mastercard, Visa

Alphanumeric, up to 25 characters.

b4payment

b4payment

ASCII, up to 128 characters.

DC Bank

Diners Club

ASCII, up to 128 characters

Eps

Eps

ASCII, up to 35 characters.

Giropay

Giropay

Variable, up to 32 characters. Allowed characters are [0-9a-zA-Z].

Hobex

SEPA Direct Debit

ASCII, up to 128 characters.

Hobex

Maestro SecureCode, Mastercard, Visa

Alphanumeric, up to 20 characters

Przelewy24

Przelewy24

ASCII, up to 64 characters.

paysafecard

paysafecard

ASCII, up to 128 characters.

payolution

payolution

ASCII, up to 128 characters.

PayPal

PayPal

ASCII, up to 128 characters.

SIX Payment Services

Maestro SecureCode, Mastercard, Visa

Not supported

SIX Pay

Maestro SecureCode, Mastercard, Visa

Not supported

Sofort

Sofort

ASCII, up to 254 characters

Wordline

Maestro SecureCode, Mastercard, Visa

Numeric and special characters between 10 and 64 characters.

SEPA

Table 18. SEPA
Parameter Within fingerprint Data type Short description

mandateId

Required if used

Alphanumeric, up to 35.

Identifier of displayed mandate.

mandateSignatureDate

Required if used

Date as DD.MM.YYYY.

Date when mandate was signed.

If mandateId is not set QENTA will generate it and if mandateSignatureDate is not set QENTA will use the current date as signature date.