Menu

User Tools

Create PDF

Site Tools


Request Parameters

General information

This page describes the request parameters for initiating the communication with the Wirecard 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.

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

Wirecard Checkout Page and Wirecard 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 Wirecard.
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 Wirecard Checkout Seamless

Parameter Within fingerprint Data type Short description
confirmUrl Required Alphanumeric with special characters. URL of your online shop where Wirecard 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

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

Parameter Within fingerprint Data type Short description
confirmUrl Required if used. Alphanumeric with special characters. URL of your online shop where Wirecard 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.

Wirecard Checkout Page and Wirecard 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.

Additionally for Wirecard 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 Wirecard 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 Wirecard 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

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

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
basketItem1UnitGrossAmount10,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
basketItem2UnitGrossAmount14,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
basketItem3UnitGrossAmount5,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.

Wirecard Checkout Page and Wirecard 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 Wirecard 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.

Wirecard Fraud Prevention Suite

If the Wirecard 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 Wirecard 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.

Wirecard 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

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

Wirecard 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 Wirecard Checkout Page and Wirecard 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 Wirecard Checkout Server.

For demo mode and for testing your integration in test mode use the relevant demo data and test data as described in Wirecard Checkout Page and Wirecard 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 Wirecard Checkout Page and Wirecard 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 Wirecard Payment Center.

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

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

paymentType

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

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

Value of parameter
paymentType
Payment method
SELECT The consumer may select one of the activated payment methods directly in Wirecard Checkout Page. Please note that SELECT is only available for Wirecard 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 Wirecard. 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 Wirecard 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 Wirecard 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 Wirecard 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 Wirecard 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 Wirecard 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 Wirecard 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 Wirecard 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 Wirecard Checkout Server to your online shop to inform your system about the result of the payment.

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

For Wirecard 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 Wirecard 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, Wirecard 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 Wirecard 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 Wirecard 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, Wirecard 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 Wirecard Checkout Server, the confirmUrl cannot be delivered and no responses may be sent. In such cases, Wirecard will continue to resend the confirmation until receiving the result="OK" or until the last re-delivery attempt was made.

In case Wirecard 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 Wirecard.

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

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 Wirecard 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, Wirecard can easily detect any identical request that has been sent in the last 30 minutes.

If you want Wirecard 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 Wirecard Checkout Seamless and optional for Wirecard 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 Wirecard 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 Wirecard Checkout Page will be delayed until a time-out for the missing image occurs. This would have no impact on the functionality of Wirecard 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 Wirecard 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 Wirecard data storage together with the customerId, shopId and storageId that only you are able to access the specific session of the Wirecard 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 Wirecard 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 Wirecard 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 Wirecard data storage of a specific consumer within a specific payment process. The storageId is valid for 30 minutes after the latest use of an intitialization, store or read operation on that data storage.

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

transactionIdentifier

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

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

  • If the parameter transactionIdentifier is not used, the value set in the merchant configuration is used.
  • If the parameter transactionIdentifier is used, the configuration settings are overwritten correspondingly.

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

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

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

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

SINGLE

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

INITIAL

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

windowName

With the parameter windowName you can define the name of the pop-up window or iframe where Wirecard 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 Wirecard Checkout Page or Wirecard 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 Wirecard 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 Wirecard 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 Wirecard Checkout Page, Wirecard Checkout Seamless or the financial service provider.
  • Communication error within Wirecard Checkout Page, Wirecard 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 Wirecard 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 Wirecard 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.


This website uses cookies to deliver the best service to you. By continuing to browse the site, you are agreeing to our use of cookies.