Data Storage

Data Storage

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

Initialization

You can initialize the QENTA Data Storage at the beginning of the payment process in your online shop. After initialization, the Data Storage session for a specific consumer is valid for 30 minutes after the last access from your 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 your consumer:

For all other supported payment methods you don’t need to store data in the Data Storage before starting the payment process itself.

To initialize the QENTA Data Storage, send a server-to-server request from your 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 your web server and 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 the correct HTTP header elements within your 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 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 you don’t use the optional parameters shopId and javascriptScriptVersion you have to omit them in your 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 you send the Data Storage 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.

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 you’ll 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 ensure that you include the returned JavaScript URL from the return parameter of the Data Storage initialization within your HTML page. Load the JavaScript at the bottom of the page to speed up the page loading time.

Include the returned JavaScript URL in PHP by the following code fragment, where $javascriptURL is the URL you have to include to your HTML page for using the JavaScript based storing functions and objects.

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

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

var dataStorage = new QentaCEE_DataStorage();

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

var paymentInformation = {};

Depending on the payment method you add various properties to this JavaScript object, e.g. for Credit Card, Credit Card-Mail Order and Telephone Order, and Maestro SecureCode you add the following properties (the values of these properties are directly taken from your 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 you only need to call a specific JavaScript function which is also available in the JavaScript file you 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 you’re able to handle the result of the storage operation and to use the following functions:

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.

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 your consumer in the QENTA Data Storage you may use the following payment-specific JavaScript functions, which you included as 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 you’ll 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 parameter brand may contain one of the following values:

Value of brand for Credit Cards

American Express

Diners Club

Discover

Mastercard

Visa

Maestro SecureCode

Mastercard ID Check

Visa Secure

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 you’re able to read at least the storageId for your current checkout of your consumer. Your Data Storage session for a specific consumer is only valid for 30 minutes after the latest read or write access from your side. After this time you have to initialize the Data Storage again and you have also to store the sensitive payment data of your consumer again.

You can use the read operation for:

  • 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 you stored to this Data Storage.

The read operation for the QENTA Data Storage, send a server-to-server request from your 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 your web server.

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

Computing the Fingerprint

If you don’t use the optional parameters shopId and javascriptScriptVersion you have to omit them in your 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.

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

Returned payment method specific parameters are dependent on the payment method your consumer chose.

If the read operation did not succeed you’ll 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