Integration Guide

Integration Guide

To start integrating the payment process in your online shop you only need to add a HTML form with some specific field names and values to your web page displaying the order details of your consumer.

Image

On QPAY Checkout Page a web page from our QENTA Checkout Server is shown to your consumer containing a HTML form. After the consumer commit the payment QPAY Checkout Page handles the entire communication with the financial service provider. After the payment process 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.

Table 1. Possible Results
State Description

SUCCESS

The payment process has been successfully completed by your consumer.

CANCEL

The payment process has been canceled by your consumer.

FAILURE

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

PENDING

The result of the payment process has yet to be determined and typically occurs on payment methods requiring additional checks. 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 and the consumer is redirected depending on the result of the payment process.

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

Image

Example you can run on your server is available at GitHub

Parameters

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 all 4 states. If for any reason your server is not reachable at the moment, the confirmation can be sent again at a later time. Contact our sales team to enable the feature.

If you did not set the optional request parameter confirmUrl but instead the optional parameter confirmMail you receive an email regarding the result of the payment. Contact our sales team to enable the 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!

If your consumer does not finish the payment process within a time frame of 30 minutes, we check the status of the payment process and sent notification to the URL set in the request parameter confirmUrl.
Optionally you have the possibility to get an e-mail for each transaction irrespective of the parameters confirmUrl or confirmMail. Contact our sales team to enable the feature.

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 plus your secret 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, and if they’re not identical, re-check the calculation.

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 to be able to identify each payment of your consumers at a later time and to correlate them to the corresponding session and order.

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.

Due to data protection regulations, we can’t provide access to the Journal for test transactions.

Display Options

When you integrate QPAY Checkout Page into your online shop, you may choose between the following display options:

Iframe

In your online shop consumers first select the desired items or services you’re selling and then start the checkout process usually by clicking the checkout button. An iframe is used to embed another web site or web page within the current HTML document. Iframes can be configured by their size and with or without scrollbars independently of the surrounding page’s scrollbars. You can integrate QPAY Checkout Page within an iframe in the HTML page of your online shop so that the whole checkout process is surrounded by your online shop and your consumer does not leave the shop.

After completing the payment process, consumers are redirected to your online shop and receive a relevant information on the result or state of the payment which is sent to the respective successUrl, cancelUrl, failureUrl or pendingUrl.

Pop-up window

In your online shop, consumers first select the desired items or services you’re selling and then start the checkout process usually by clicking the checkout button. QPAY Checkout Page opens as a new browser window in front of the main window overlaying your online shop.

After completing the payment process, the pop-up window is closed by QENTA, consumers are redirected to your online shop and receive a relevant information on the result or state of the payment which is sent to the respective successUrl, cancelUrl, failureUrl or pendingUrl.

Many web browsers usually offer an option to block pop-up windows which are typically enabled by default.

QPAY Checkout Page redirects the consumer by default with a pop-up to all alternative payment methods. This might result in two pop-ups consecutively opening during the checkout process. The exception being cards with 3-D Secure which will be displayed as iframe within QPAY Checkout Page or optionally as a page redirect.

When integrating QPAY Checkout Page in a pop-up window, the external pages of financial institutions can be displayed as an additional pop-up or as a page redirect in the pop-up window.

Page redirect

In your online shop, consumers first select the desired items or services you’re selling and then start the checkout process usually by clicking the checkout button. QPAY Checkout Page opens by redirecting your consumers automatically from your online shop to QPAY Checkout Page which replaces your online shop entirely in the browser window. The QENTA-URL is displayed in the address bar.

After completing the payment process, consumers are redirected to your online shop and receive a relevant information on the result or state of the payment which is sent to the respective successUrl, cancelUrl, failureUrl or pendingUrl.

Use the user interface customization possibilities so that your consumer still has the feeling to be in your shop.

When integrating QPAY Checkout Page as a page redirect, the external pages of financial institutions can be displayed as a pop-up or as another redirect to the financial service provider.

If you need various display options for additional pages from the financial service provider a different shopId can be requested and a different configuration can be set. Contact our integration specialists.