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.

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.

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.
`displayBasketData`	Optional	Enumeration	`N`- Don’t display Basket Items.

Provide basket items to init or via QPBL 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 QPBL 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
Riverity	Riverity	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
Riverity	Riverity	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.