Data Storage

The QENTA Data Storage is used for storing sensitive payment data of the consumer during the payment process of the online shop. By using the functionality merchant is able to retrieve, send and store e.g. credit card numbers of the consumer without using the web server. This ensures that online shops and web servers don’t need to be PCI-compliant.

Initialization

QENTA Data Storage can be initialized at the beginning of the payment process in the online shop. After initialization, the Data Storage session for a specific consumer is valid for 30 minutes after the last access from the online shop to the Data Storage. After 30 minutes the session becomes invalid and a new Data Storage has to be initialized.

For PHP we provide an example code on GitHub.

The QENTA Data Storage is only required for the following payment methods which manage sensitive payment data of the consumer:

Credit Card
Credit Card-Mail Order and Telephone Order
Maestro SecureCode
SEPA Direct Debit

For all other supported payment methods data doesn’t need to be stored in the Data Storage before starting the payment process itself.

To initialize the QENTA Data Storage, send a server-to-server request from the web server to a specific URL containing some specific request parameters: https://api.qenta.com/seamless/dataStorage/init.

Enable server-to-server requests within the configuration of the web server and firewall settings for sending data from the server to api.qenta.com (212.183.46.16/28).

For a valid request, the correct HTTP header elements have to be set within the request:

Table 1. HTTP Header Parameters
HTTP header parameter	Description and value
`Host`	Domain name of server, value: `api.qenta.com`
`User-Agent`	User agent string of client
`Content-Type`	MIME type of the body, value: `application/x-www-form-urlencoded`
`Content-Length`	Length of the body in bytes
`Connection`	Type of connection, value: `close`

Incorrect setting of the header parameters results in an HTTP 403 error message of the QENTA Checkout Server.

Computing the fingerprint

If the optional parameters shopId and `javascriptScriptVersion`are not used then they must be omitted in the fingerprint string.

Concatenation of the request parameters and the secret has to be done in the following order: customerId,shopId,orderIdent,returnUrl,language,javascriptScriptVersion,secret

Parameters

Required, optional request and response parameters for Initialization of QENTA Data Storage.

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

For example, a successful initiation of the QENTA Data Storage would return:

storageId=73171af0b8990b9ef2d11b2070f54ad3&javascriptUrl=\https://api.qenta.com/seamless/dataStorage/init/js/D200001/seamless/73171af0b8990b9ef2d11b2070f54ad3/dataStorage.js

If the initialization did not succeed the merchant will get parameters describing the error.

Example of possible error:

error.1.errorCode=11500&error.1.message=CUSTOMERID+is+missing.&error.2.errorCode=11009&error.2.message=Language+is+missing.&error.3.errorCode=15300&error.3.message=ORDERIDENT+has+an+invalid+length.&error.4.errorCode=11301&error.4.message=RETURNURL+is+missing.&error.5.errorCode=11506&error.5.message=REQUESTFINGERPRINT+is+missing.&errors=5

Storing sensitive payment data

Before using the store operation the merchant should ensure that is the returned JavaScript URL included in the return parameter of the Data Storage initialization within the HTML page. Load the JavaScript at the bottom of the page to speed up the page loading time.

JavaScript URL in PHP by the following code fragment should be included, where $javascriptURL is the URL the merchant has to include to the HTML page for using the JavaScript-based storing functions and objects.

<script src="<?php echo $javascriptURL; ?>" type="text/javascript"></script>

Then create an instance of the JavaScript class QentaCEE_DataStorage, which is defined within the previously included URL.

var dataStorage = new QentaCEE_DataStorage();

Then create a new and empty JavaScript object which will be filled with the sensitive payment data:

var paymentInformation = {};

Depending on the payment method the merchant adds various properties to this JavaScript object, e.g. for Credit Card, Credit Card-Mail Order and Telephone Order, and Maestro SecureCode add the following properties (the values of these properties are directly taken from the HTML form by accessing the values of the form elements via the DOM of the web browser):

paymentInformation.pan = document.getElementById('cc_pan').value;
paymentInformation.expirationMonth = document.getElementById('cc_expirationMonth').value;
paymentInformation.expirationYear = document.getElementById('cc_expirationYear').value;
paymentInformation.cardholdername = document.getElementById('cc_cardholdername').value;
paymentInformation.cardverifycode = document.getElementById('cc_cardverifycode').value;
paymentInformation.issueMonth = document.getElementById('cc_issueMonth').value;
paymentInformation.issueYear = document.getElementById('cc_issueYear').value;
paymentInformation.issueNumber = document.getElementById('cc_issueNumber').value;

After setting all properties to the paymentInformation object the merchant only needs to call a specific JavaScript function which is also available in the JavaScript file that is included before:

Credit Card

dataStorage.storeCreditCardInformation(paymentInformation, callbackFunction);

Credit Card-Mail Order and Telephone Order

dataStorage.storeCreditCardMotoInformation(paymentInformation, callbackFunction);

Maestro SecureCode

dataStorage.storeMaestroInformation(paymentInformation, callbackFunction);

The callbackFunction is a JavaScript function where the merchant is able to handle the result of the storage operation and use the following functions:

Function Descritpion

Function	Descritpion
`getStatus()`	Returns 0 for a successful storage operation otherwise 1.
`getAnonymizedPaymentInformation()`	Returns anonymized payment information as a simple JavaScript object.
`getErrors()`	Returns the errors as a simple JavaScript object.

getStatus()

Returns 0 for a successful storage operation otherwise 1.

getAnonymizedPaymentInformation()

Returns anonymized payment information as a simple JavaScript object.

getErrors()

Returns the errors as a simple JavaScript object.

A very simplified example of this callback function can be:

callbackFunction = function(aResponse) {
  // initiates the result string presented to the user
  var s = "Response of QENTA Data Storage call:\n\n";
  // checks if response status is without errors
  if (aResponse.getStatus() == 0) {
    // saves all anonymized payment information to a JavaScript object
    var info = aResponse.getAnonymizedPaymentInformation();

    //Response for paymentTypes: CCARD, CCARD-MOTO, MAESTRO
    s + = "Response for paymentTypes: CCARD, CCARD-MOTO, MAESTRO\n";
    s += "anonymousPan: " + info.anonymousPan + "\n";
    s += "maskedPan: " + info.maskedPan + "\n";
    s += "financialInstitution: " + info.financialInstitution + "\n";
    s += "brand: " + info.brand + "\n";
    s += "cardholdername: " + info.cardholdername + "\n";
    s += "expiry: " + info.expiry + "\n";

    //Response for paymentType: SEPA-DD
    s + = "Response for paymentType: SEPA-DD\n";
    s += "bankBic: " + info.bankBic + "\n";
    s += "bankAccountIban: " + info.bankAccountIban + "\n";
    s += "accountOwner: " + info.accountOwner + "\n";

  } else {
    // collects all occurred errors and adds them to the result string
    var errors = aResponse.getErrors();
    for (e in errors) {
      s += "Error " + e + ": " + errors[e].message + " (Error Code: " + errors[e].errorCode + ")\n";
    }
  }
  // presents result string to the user
  alert(s);
}

To store the sensitive data of the consumer in the QENTA Data Storage the merchant should use the following payment-specific JavaScript functions, which are included as a JavaScript file before.

dataStorage.storeCreditCardInformation(paymentInformation, callbackFunction);

dataStorage.storeCreditCardMotoInformation(paymentInformation, callbackFunction);

dataStorage.storeMaestroInformation(paymentInformation, callbackFunction);

dataStorage.storeSepaDdInformation(paymentInformation, callbackFunction);

If the initialization did not succeed the merchant will get parameters describing the error.

Parameters

Required, optional request and response parameters for payment methods Credit Card, Credit Card-Mail Order and Telephone Order, and MaestroSecureCode.

The optional parameter brand may contain one of the following values:

Table 2. Value of brand for Credit Cards
American Express
Diners Club
Discover
Mastercard
Visa
Maestro SecureCode

SEPA Direct Debit

Required request and optional request parameters for SEPA Direct Debit.

Code example for setting the properties within the paymentInformation JavaScript object:

paymentInformation.bankBic = document.getElementById('sepa-dd_bankBic').value;
paymentInformation.bankAccountIban = document.getElementById('sepa-dd_bankAccountIban').value;
paymentInformation.accountOwner = document.getElementById('sepa-dd_accountOwner').value;

Reading stored payment data

After initializing the Data Storage the merchant is able to read at least the storageId for the current checkout of the consumer. The Data Storage session for a specific consumer is only valid for 30 minutes after the latest read or write access from the merchant side. After this time the merchant have to initialize the Data Storage again and to has also to store the sensitive payment data of the consumer again.

Testing if the session with that storageId is still valid or already invalidated.
Extending the session lifetime for another 30 minutes.
Reading sensitive payment data that are stored to this Data Storage.

The read operation for the QENTA Data Storage, sends a server-to-server request from the web server to a specific URL containing some specific request parameters: https://api.qenta.com/seamless/dataStorage/read.

Enable server-to-server requests within the configuration of the web server.

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

Computing the Fingerprint

If the optional parameters shopId and `javascriptScriptVersion`are not used then they must be omitted in the fingerprint string.

Concatenation of the request parameters and the secret has to be done in the following order: customerId,shopId,storageId.

Parameters

Required, optional request and response parameters for Reading Stored Payment Data.

Returned payment method specific parameters are dependent on the payment method the consumer chooses.

If the read operation did not succeed the merchant will get parameters describing the error.

An example of a possible error:

error.1.errorCode=11500&error.1.message=CUSTOMERID+is+missing.&error.2.errorCode=11506&error.2.message=REQUESTFINGERPRINT+is+missing.&errors=2