Seamless Payment Process

Seamless Payment Process

Initiating the payment process

After initializing the Data Storage you’re able to start the payment of all payment methods which don’t need to store sensitive data in the QENTA Data Storage. If you support payments which involve the handling of sensitive data you need to store these data to the Data Storage before you start the payment process.

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

The starting of the payment process you send a server-to-server request from your webserver 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 your web server. The issue arises typically on provider-managed web servers with PHP.

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

Check how is fingerprint computed.

Return values from the server-to-server initiation request

After you send the initiation request as a server-to-server request from your web server to the QENTA Checkout Server you’ll 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 you’ll receive a parameter called redirectUrl which you use to redirect your consumer to the next page within the payment process. Typically your 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

redirectUrl

Alphanumeric

URL to redirect your consumer.

If the initialization did not succeed you’ll get parameters describing the error.

Simplified code example for redirecting your 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 result of the payment process

There are four possible results which 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 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. 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.

Receiving result of payment process

After your consumer has finished the payment process, QMORE Checkout Seamless sends the result to your 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 your system

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

  • successUrl

  • cancelUrl

  • failurUrl

  • 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 your 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 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.

Storing payment results in your online shop

Connection problems and technical issues on your web server may result in a loss of session-related information regarding your 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 your 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 your custom parameters are returned to your 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 you receive from the QENTA Checkout Server. Also ensure that you can relate them to the initial data regarding the payment process.

QENTA Checkout Journal

To check your integration of QMORE Checkout Seamless you may use QENTA Checkout Journal as a debugging tool that 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.