LATEST VIEWED
- No pages viewed yet
Sidebar
Table of Contents
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 http://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.
Additionally if you are using the QENTA Fraud Prevention & Fraud Detection some parameters may be required.
| 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 special characters and a variable length of up to 64. | Consumer identifier in your shop. Requests from the same consumer must contain the same identifier. |
| 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. |
QENTA Fraud Prevention Suite
If the QENTA Fraud Prevention Suite (FPS) has been enabled upon your request, you can use the following optional request parameters for each individual transaction to overwrite your default configured behavior.
| Parameter | Within fingerprint | Data type | Short description |
|---|---|---|---|
| riskSuppress | Required if used. | Boolean | Enables or disables a risk check. |
| riskConfigAlias | Required if used. | Alphanumeric with a variable length between 1 and 16. | Selection of the used risk rule. |
Please be aware that you can use the FPS only for the following payment types: CCARD and CCARD-MOTO.
To enable the FPS, please contact our sales teams.
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:
https://www.yourwebshop.com/success.php?yourWebShopName_customValueXYZ=aCustomValue
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. |
| Lybian 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 the 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. ä 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 parameterpaymentType | 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. |
| BANCONTACT_MISTERCASH | Bancontact/Mister Cash |
| CCARD | Credit Card, Maestro SecureCode |
| CCARD-MOTO | Credit Card - Mail Order and Telephone Order |
| EPAY_BG | ePay.bg |
| EPS | eps-Überweisung |
| GIROPAY | giropay |
| IDL | iDEAL |
| INSTALLMENT | Installment: payolution or Installment: RatePAY |
| INVOICE | Invoice: payolution, Invoice: RatePAY or Invoice by Wirecard |
| MAESTRO | Maestro SecureCode |
| MASTERPASS | Masterpass |
| MONETA | moneta.ru |
| PRZELEWY24 | Przelewy24 |
| PAYPAL | PayPal |
| PBX | paybox |
| POLI | POLi |
| PSC | paysafecard |
| SEPA-DD | SEPA Direct Debit |
| SKRILLWALLET | Skrill Digital Wallet |
| SOFORTUEBERWEISUNG | Sofort. |
| TATRAPAY | TatraPay |
| TRUSTLY | Trustly |
| TRUSTPAY | TrustPay |
Deprecated payment methods
Some payment methods have become outdated and are no longer supported by QENTA. Deprecated payment methods gives an overview of all outdated payment methods.
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 195.93.244.97, 185.60.56.35 and 185.60.56.36.
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 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
confirmUrlcannot be delivered and no responses may be sent. In such cases, QENTA will continue to resend the confirmation until receiving theresult="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.
Remember that the payment methods EPS and IDL only allow one value, while other payment methods like Credit Cards allow a comma-separated list of values.
Value of parameter paymentType | Possible value(s) of parameter financialInstitution | Description |
|---|---|---|
| BANCONTACT_MISTERCASH | Bancontact/Mister Cash | Bancontact/Mister Cash |
| CCARD / CCARD-MOTO / MASTERPASS | MC | Mastercard |
| MCSC | Mastercard SecureCode | |
| Maestro | Maestro SecureCode | |
| Visa | Visa | |
| VbV | Verified by Visa | |
| Amex | American Express | |
| amexsafekey | American Express SafeKey | |
| Diners | Diners Club | |
| Discover | Discover | |
| JCB | JCB | |
| J/Secure | J/Secure™ | |
| CCARD / CCARD-MOTO | UATP | Universal Airline Travel Plan |
| EPAY_BG | ePay.bg | ePay.bg |
| EPS | 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 | |
| GIROPAY | GIROPAY | giropay |
| IDL | 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 | |
| INVOICE | payolution | payolution |
| RatePAY | RatePAY | |
| Wirecard | Wirecard | |
| INSTALLMENT | payolution | payolution |
| RatePAY | RatePAY | |
| MAESTRO | Maestro | Maestro SecureCode |
| MONETA | moneta.ru | moneta.ru |
| PAYPAL | PAYPAL | PayPal |
| PBX | PBX | Mobile Phone Invoice |
| POLI | POLi | POLi |
| PRZELEWY24 | Przelewy24 | Przelewy24 |
| SEPA-DD | SEPA-DD | SEPA Direct Debit |
| SKRILLWALLET | Skrill Digital Wallet | Skrill Digital Wallet |
| SOFORTUEBERWEISUNG | SOFORTUEBERWEISUNG | Sofort. |
| TATRAPAY | TatraPay | TatraPay |
| TRUSTLY | TRUSTLY | Trustly |
| TRUSTPAY | Bank ID of used bank | TrustPay |
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.
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 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.
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 |
|---|---|---|---|
| BANCONTACT_MISTERCASH | ✔ | ||
| CCARD | ✔ | ||
| EPAY_BG | ✔ | ||
| EPS | ✔ | ||
| GIROPAY | ✔ | ||
| IDL | ✔ | ||
| INSTALLMENT | ✔ | ||
| INVOICE | ✔ | ||
| MAESTRO | ✔ | ||
| MASTERPASS | ✔ | ||
| MONETA | ✔ | ||
| PRZELEWY24 | ✔ | ||
| PAYPAL | ✔ | ||
| PBX | ✔ | ||
| POLI | ✔ | ||
| PSC | ✔ | ||
| SEPA-DD | ✔ | ||
| SKRILLWALLET | ✔ | ||
| SOFORTUEBERWEISUNG | ✔ | ||
| TATRAPAY | ✔ | ||
| TRUSTLY | ✔ | ||
| TRUSTPAY | ✔ |
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
transactionIdentifieris not used, the value set in the merchant configuration is used. - If the parameter
transactionIdentifieris 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 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.