Integration Guide

Integration Guide


To start integrating the payment process in your online shop you only need to add an HTML-form with some specific field names and values to your web page displaying the order details of your consumer. By submitting the form, and thus submitting the defined values, your consumer is forwarded to QPAY Checkout Page.


On QPAY Checkout Page a web page from our QENTA Checkout Server is shown to your consumer containing an HTML-form where entering of sensitive financial data is possible in a secure manner. After entering these data, your consumer commits the payment and QPAY Checkout Page handles the entire communication with the financial service provider.

After the payment process on the part of the financial service provider is completed, QPAY Checkout Page informs your online shop about the result of the payment and forwards the consumer to a specific URL in your online shop which depends on the result of the payment process.

Your online shop and your web server do not need to be PCI-compliant because all financial issues are handled by QPAY Checkout Page which is hosted on the QENTA Checkout Server and is itself PCI-compliant and certified for managing and storing sensitive financial data of your consumers like credit card numbers.

There are four possible results which can be returned from QPAY Checkout Page to your online shop:

State Description


The payment process has been successfully completed by your consumer.


The payment process has been canceled by your consumer.


The payment process has not been finished successfully by your consumer.


The result of the payment process has yet to be determined. Typically occurs on payment methods requiring additional checks or actions by financial service providers or your consumer. When QENTA retrieves updated information from the financial service provider, either a success or a failure is sent to your online shop. Please be aware that the state pending is only used if the request parameter pendingUrl is used.

For each possible result state a corresponding URL on your web server is called by the QENTA Checkout Server. These URLs are defined in the HTML form when starting the payment process. Your consumer is redirected to the corresponding URL depending on the result of the payment process.

Additionally, QENTA sends the result of the payment process to the confirmUrl. Therefore it is required that your production or test web server is accessible from the Internet. The integration example below is not fully functional on your local host which is typically not accessible from the Internet due to routers, firewalls and security restrictions!

A graphical overview of the communication between your online shop and QPAY Checkout Page from a technical point of view is shown below.


Starting the payment process

The payment process can be initiated in your online shop by adding an HTML-form to the page you want to start the payment process from.

This form consists of a request with required parameters, such as customerId, language, amount, currency, and optional parameters, e.g. confirmUrl, orderNumber, customerStatement. These parameters are hidden and not presented to your consumer in your online shop. For all possible request parameters please refer to Request Parameters.

All parameters are sent as a POST request to the URL

The following example can be copied into an html file. When opened in a browser, QPAY Checkout Page opens on clicking "submit". Only the payment process results will not be sent as the URLs are not valid.

<form action='' method='post' name='checkout' target='_self'>
  <input type='hidden' name='customerId' value='D200001' />
  <input type='hidden' name='language' value='en' />
  <input type='hidden' name='paymentType' value='SELECT' />
  <input type='hidden' name='amount' value='39.90' />
  <input type='hidden' name='currency' value='EUR' />
  <input type='hidden' name='orderDescription' value='Order 12345 6789 0' />
  <input type='hidden' name='successUrl' value='' />
  <input type='hidden' name='cancelUrl' value='' />
  <input type='hidden' name='failureUrl' value='' />
  <input type='hidden' name='pendingUrl' value='' />
  <input type='hidden' name='confirmUrl' value='' />
  <input type='hidden' name='serviceUrl' value='' />
  <input type='hidden' name='displayText' value='Thank you very much for your order.' />
  <input type='hidden' name='imageUrl' value='' />
  <input type='hidden' name='requestFingerprintOrder' value='customerId,language,amount,currency,orderDescription,paymentType,successUrl,cancelUrl,failureUrl,pendingUrl,confirmUrl,serviceUrl,displayText,imageUrl,requestFingerprintOrder,secret' />
  <input type='hidden' name='requestFingerprint' value='C33633657B27DD42323BF46F123F06944519AA9A0BD741700790E17A057D4751D9767B3F5225033CF74547AAD16C7BDB32FF15970E5D0F640EE58931ADEE7AFC' />
  <input type='hidden' name='windowName' value='' />
  <input type='submit' name='submit' value='Start Checkout'>

A fully functional example to run on your server is available as example code on GitHub.

Please configure your firewall settings for sending data from your server to ( correspondingly.

Demo and test mode

For data to test your integration, i.e. demo values for payment method specific values, please refer to demo mode and test mode.

Receiving the payment process result

QPAY Checkout Page informs your online shop about the result of your consumers payment by calling one of the URLs you provided when starting the payment process. The call includes values which can be used for further processing.

The payment process can result in one of four possible states as described above: Success, Cancel, Failure or Pending. For each state, the corresponding specific URL is called and QPAY Checkout Page submits return parameters in a POST request to the corresponding URL. Please visit Response Parameters for a detailed description of the parameters you receive which may vary depending on the payment method.

Additionally, if the optional request parameter confirmUrl is set, QPAY Checkout Page calls the given URL with a 30 second timeout using the same return values as for successUrl, cancelUrl, failureUrl or pendingUrl. If for any reason your server is not reachable at the moment, the confirmation can be sent again at a later time. Please contact our support teams to enable this feature.

If you did not set the optional request parameter confirmUrl but instead the optional parameter confirmMail, you receive an e-mail regarding the result of the payment. Please contact our sales teams to enable this feature.

If you set neither the confirmUrl nor confirmMail you may not be informed about the result of the payment process if your consumer closes the browser window prematurely!

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

If your consumer does not finish the payment process within a time frame of 30 minutes, we check if the payment has been successfully completed. If the result of the check is a successful payment, a success notification is sent to the URL set in the request parameter confirmUrl. If the payment is not successful a failure notification is sent to the same URL instead. Therefore we strongly recommend setting the confirmUrl!

Checking if returned values are valid

To check the authenticity of the return values sent from the QENTA Checkout Server to your online shop, compare the responseFingerprint with an hash of the return values.

Create a string by concatenating all returned parameters based on the order in the return parameter responseFingerprintOrder. Then hash the string with an HMAC-SHA-512 algorithm using the secret as cryptographic key and compare the result with the value of the return parameter responseFingerprint. If both values are identical, the response is authentic, i.e. the confirmation was indeed sent by QENTA. If these values are not identical, re-check the calculation and consider that someone compromised the return values or has sent a possibly false confirmation for the payment. Therefore, do not trust these return values and do not assume that the payment was made even if it appears that way to you!

In order to ensure a secure communication it is essential that you never disclose or share your secret with persons who are not involved in developing the online shop! Also, never forward the secret via unsecured communication channels e.g. mail, e-mail, fax or instant messaging. When the secret is submitted by fax make sure that the contents of the fax is disclosed only to authorized persons!

If you suspect that your secret is known to unauthorized persons contact our support teams immediately to request a new secret!

Storing the payment process result

To ensure a persistent storage of all data relevant to the payment process of your consumers, it is strongly recommended to save all relevant data either in a file or in a database.

Payment related data

Please note that connection problems, technical issues on your web server or any issues at your consumer may result in a loss of session-related information regarding your consumer, e.g. the content of the shopping cart or an already generated unique order number for a specific order. Especially if the consumer successfully finished the payment process it may not be possible to correlate the session-related information regarding the order details to the successful payment of your consumer.

To prevent such situations we strongly recommend that you store all session-related information during the overall payment process persistently, e.g. in a file or a database.

Also use the possibility of custom parameters to pass a unique ID corresponding to a payment process to QPAY Checkout Page. All of your custom parameters are returned to your online shop as return values after the payment process has been finished.

Return values

To be able to identify each payment of your consumers at a later time and to correlate them to the corresponding session and order, store all return values of QPAY Checkout Page in relation to that session and order. This is required to ensure a well-defined relation between the session data, the order of your consumer and the results of the payment process.

Therefore, save all return values after the payment process or at least the returned order number you received by QPAY Checkout Page via successUrl, cancelUrl, failureUrl, pendingUrl or the confirmUrl. Also ensure that you can relate the values to the data you saved before starting QPAY Checkout Page.

Displaying the payment process result to consumers

At the end of each payment process, QPAY Checkout Page calls, if provided, the confirmUrl and then forwards your consumer to one of the URLs you defined via the request parameters successUrl, cancelUrl, pendingUrl or failureUrl.

Best Practices

Before starting a payment process and in order to avoid pitfalls ensure that the following issues are fulfilled:

  • Save all relevant data regarding the payment process in a persistent manner, e.g. in a file or a database, including all request parameter values.

  • In the required request parameter orderDescription set a unique ID regarding the session of your consumer. This can be a sessionId, an order number or a debit number.

  • The response parameters are validated via the fingerprint and you are alerted to any failed validations.

QENTA Checkout Journal

To check your integration of QPAY Checkout Page you may use QENTA Checkout Journal as a debugging tool which gives you an overview of your transaction details when doing a checkout.

Note that due to data protection regulations no test mode transactions are possible.

Please enter the username and password you receive from QENTA to have access to all transactions regarding your specific customerId.

QENTA Checkout Journal