Seamless Payment Process

Initiating the payment process

After initializing the Data Storage the merchant is able to start the payment of all payment methods which don’t need to store sensitive data in the QENTA Data Storage. If the merchant supports payments that involve the handling of sensitive data then he needs to store these data in the Data Storage before the merchant starts the payment process.

Data Storage session for a specific consumer is only valid for 30 minutes. Once this period of time has expired, the merchant has to initialize the Data Storage again and also has to store the sensitive payment data of the consumer again.

At the start of the payment process, the merchant sends a server-to-server request from the web server to the QENTA Checkout Server to a specific URL containing some specific request parameters: https://api.qenta.com/seamless/frontend/init.

It’s sometimes necessary to enable server-to-server requests in the configuration of the web server. The issue arises typically on provider-managed web servers with PHP.

For a proper request, the merchant has to set the correct HTTP header elements within the request.

Check how is fingerprint computed.

Return values from the server-to-server initiation request

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

If the initiation of the payment process was successful the merchant will receive a parameter called redirectUrl which he uses to redirect the consumer to the next page within the payment process. Typically the consumer is redirected to pages of financial institutions like internet banking pages or a page for entering the 3-D Secure code.

Parameter Data type Description

Parameter	Data type	Description
`redirectUrl`	Alphanumeric	URL to redirect the consumer.

redirectUrl

Alphanumeric

URL to redirect the consumer.

If the initialization did not succeed the error parameters will be received.

Simplified code example for redirecting the consumer or retrieving errors if they occurred within the initiation:

//--------------------------------------------------------------------------------//
// Retrieves the value for the redirect URL.
//--------------------------------------------------------------------------------//

$redirectURL = "";
foreach (explode('&', $curlResult) as $keyvalue) {
  $param = explode('=', $keyvalue);
  if (sizeof($param) == 2) {
    $key = urldecode($param[0]);
    if ($key == "redirectUrl") {
      $redirectURL = urldecode($param[1]);
      break;
    }
  }
}

//--------------------------------------------------------------------------------//
// Redirects consumer to payment page.
//--------------------------------------------------------------------------------//

if ($redirectURL == "") {
  echo "<pre>";
  echo "Frontend Intitiation failed with errors:\n\n";
  foreach (explode('&', $curlResult) as $keyvalue) {
    $param = explode('=', $keyvalue);
    if (sizeof($param) == 2) {
      $key = urldecode($param[0]);
      $value = urldecode($param[1]);
      echo $key . " = " . $value . "\n";
    }
  }
  echo "</pre>";
} else {
  header("Location: " . $redirectURL);
}

Handling the result of the payment process

Four possible results can be returned from QMORE Checkout Seamless to the confirmUrl:

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. Typically occurs on payment methods requiring additional checks or actions by financial service providers or the consumer. When QENTA retrieves updated information from the financial service provider, either a success or a failure is sent to the online shop.

Receiving the result of a payment process

After the consumer has finished the payment process, QMORE Checkout Seamless sends the result to the online shop and the data is sent as a POST request. Be aware that the response parameters are only sent to the confirmUrl and not to the successUrl, cancelUrl, failureUrl or pendingUrl.

The result of the payment can be processed depending on the parameter paymentState as shown in this simplified example:

$paymentState = isset($_POST["paymentState"]) ? $_POST["paymentState"] : "undefined";

$message = "The message text has not been set.";
if (strcmp($paymentState, "CANCEL") == 0) {
  $message = "The payment transaction has been canceled by the consumer.";
} else
if (strcmp($paymentState, "PENDING") == 0) {
  $message = "The payment is pending and not yet finished.";
} else
if (strcmp($paymentState, "FAILURE") == 0) {
  $failure_message = isset($_POST["message"]) ? $_POST["message"] : "";
  $message = "An error occurred during the payment transaction: " . $failure_message;
} else
if (strcmp($paymentState,"SUCCESS") == 0) {
  // check fingerprint and handle successful payment
  $message = "The payment has been successfully completed.";
}

// store message and additional response parameter on the system

After the result of the payment which was effected by consumer is sent to the confirmUrl on the web server, the consumer is redirected to one of the following URLs provided in the request parameters:

successUrl
cancelUrl
failureUrl
pendingUrl

No additional parameters are sent when redirecting to one of these URLs.

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

Checking if returned values are valid

Create a string by concatenating all returned parameters plus 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 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.

Storing payment results in online shop

Connection problems and technical issues on the web server may result in a loss of session-related information regarding consumer, e.g. the content of the shopping cart.

Before starting the payment process in QMORE Checkout Seamless:

Save all relevant data regarding the payment process in a persistent manner.
Set the request parameter orderIdent to a unique ID regarding the session and order of consumer (session ID, an order number or a debit number).
Use custom parameters to pass a unique ID corresponding to a payment process to the QENTA Checkout Server. All of the custom parameters are returned to the online shop as return values after the payment process has been completed.

After the payment process is completed:

Save all returned values or at least the returned order number the merchant receives from the QENTA Checkout Server. Also, the merchant can relate them to the initial data regarding the payment process.

QENTA Checkout Journal

To check the integration of QMORE Checkout Seamless QENTA Checkout Journal can be used 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.