Integration Guide

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

On QPAY Checkout Page a web page from our QENTA Checkout Server is shown to the consumer containing an 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 the online shop about the result of the payment and forwards the consumer to a specific URL in the 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 the consumer.
`CANCEL`	The payment process has been canceled by the consumer.
`FAILURE`	The payment process has not been finished successfully by the 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 the web server is called by the QENTA Checkout Server and the consumer is redirected depending on the result of the payment process.

Figure 1. Graphical overview of the communication between the online shop and QPAY Checkout Page

See the example available on GitHub that can run on the server.

Parameters

confirmUrl

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 the server is not reachable at the moment, the confirmation can be sent again at a later time.
If the optional request parameter confirmUrl is not set, but instead optional parameter confirmMail, an e-mail regarding the result of the payment will be received.
If neither the confirmUrl nor confirmMail is set, the merchant may not be notified of the payment process outcome (if the consumer closes the browser window prematurely!).
If the consumer does not finish the payment process within a time frame of 30 minutes, we check the status of the payment process and sent a notification to the URL set in the request parameter confirmUrl.
An e-mail for each transaction irrespective of the parameters confirmUrl or confirmMail is possible to get.

Contact our sales team to enable the features above.

responseFingerprint

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

Create a string by concatenating all returned parameters and the secret based on the order in the return parameter responseFingerprintOrder. Then hash the string with an HMAC-SHA-512 algorithm using the secret as a 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, re-check the calculation.

Save all return values after the payment process, or at least the returned order number received from QPAY Checkout Page via successUrl, cancelUrl, failureUrl, pendingUrl, or the confirmUrl, to be able to identify each payment of consumers at a later time and to correlate them to the corresponding session and order.

QENTA Checkout Journal

To check the integration of QPAY Checkout Page use QENTA Checkout Journal as a debugging tool that gives an overview of transaction details when doing a checkout.

Due to data protection regulations access to the Journal for test transactions can’t be provided.

Display Options

To integrate QPAY Checkout Page into the online shop choose between the following display options:

Page redirect

In the online shop, consumers first select the desired items or services and start the checkout process usually by clicking the checkout button. QPAY Checkout Page opens by redirecting the consumers automatically from the online shop to QPAY Checkout Page which replaces the 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 the online shop and receive 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 the consumer still has the feeling to be in the online 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.
Iframe

Iframe integration is not recommended due to compatibility issues with certain financial institutions.

In the online shop, consumers first select the desired items or services and start the checkout process usually by clicking the checkout button. An iframe embeds another website or a 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. QPAY Checkout Page can be integrated within an iframe in the HTML page of the online shop so that the whole checkout process is surrounded by the online shop and the consumer does not leave the shop.

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

Pop-up window integration is not recommended, because web browsers usually offer an option to block pop-up windows which are typically enabled by default.

In the online shop, consumers first select the desired items or services and 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 the online shop.

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

NOTE:

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 is cards with 3-D Secure which will be displayed as an 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.

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