Technical Implementation for QPAY Checkout Page

Technical Implementation for QPAY Checkout Page

This chapter provides detailed information on the technical implementation of back-end operations, both of transaction-based and non-transaction-based operations, in connection with QPAY Checkout Page.

For a full description of all back-end operations for QPAY Checkout Page and QMORE Checkout Seamless go to Back-end operations.

Starting an operation

To start an operation, send a server-to-server request from your web server to the following URL at the QENTA Checkout Server:

https://api.qenta.com/page/toolkit.php

Additionally you have to set specific parameters depending on the operation you want to use. You can get a list of all possible transaction based back-end operations using the operation getOrderDetails, which is always available.

Please be aware that it is sometimes necessary to enable server-to-server requests in the configuration of your web server. This issue arises typically on provider managed web servers with PHP.

Please also configure your firewall settings for sending data from your server to api.qenta.com (212.183.46.16/28).

For a proper request you have to set a correct HTTP header. Therefore you need to set the following HTTP header elements within your request:

HTTP header parameter Description

Host

Domain name of server. Has to be set to the following value: api.qenta.com

User-Agent

User agent string of client.

Content-Type

MIME type of the body. Has to be set to the following value: application/x-www-form-urlencoded

Content-Length

Length of body in bytes.

Connection

Type of connection. Has to be set to the following value: close

Please be aware that an incorrect setting of the header parameters results in an HTTP 403 error message of the QENTA Checkout Server.

Computing the fingerprint

The fingerprint is computed by concatenating all request parameters without any dividers in between and using the secret as cryptographic key for the hashing function. If you do not use optional parameters you have to omit them in your fingerprint string.

Please be aware that the concatenation of the request parameters has to be done in the order as defined within the detailed description of each operation.

After concatenating all values to a single string create an HMAC-SHA-512 hash with your secret as cryptographic key. The result is the fingerprint which you add as a request parameter to the server-to-server call.

The QENTA Checkout Server is thus able to check whether the received parameters are manipulated by a 3rd party. Therefore it is essential to keep your secret safe!

Required request parameters for all operations

To start an operation you have to set all required parameters to their corresponding values. If one or more of these required parameters are missing you will get an error message.

Parameter Data type Short description

customerId

Alphanumeric with a fixed length of 7.

Unique ID of merchant.

toolkitPassword

Alphanumeric with special characters.

Your password for back-end operations using QPAY Checkout Page (formerly Toolkit light).

command

Enumeration

Operation to be executed.

language

Alphabetic with a fixed length of 2.

Language for returned texts and error messages, currently only "en" is supported; we are able to integrate other languages upon request.

requestFingerprint

Alphanumeric with a fixed length of 128.

Computed fingerprint of the parameter values and the secret.

For testing purposes in demo mode and customerId D200001, the value jcv45z is to be used as toolkitPassword.

Optional request parameters

Parameter Data type Short description

shopId

Alphanumeric with a variable length of 16.

Unique ID of your online shop if several configurations are used within one customerId.

Format of return values

After you send the request as a server-to-server request from your web server to the QENTA Checkout Server you will get the result of the operation as key-value pairs returned in the content of the response.

These key-value pairs depend on the result of the request and are described in detail in response parameters.