Datatrans

Time to read: 14 minutes


PepperShop with Datatrans

The connection to the payment service provider Datatrans is already integrated in the PepperShop and free of charge. Every new shop version brings an updated interface to Datatrans from day 1.

These instructions explain how to set up and handle e-payment payments that are recorded and processed by Datatrans. Datatrans is one of the most beautiful and easiest to use payment terminals in e-commerce. In addition, you can choose from many means of payment.

Information about the Datatrans connection:

  • Datatrans can be used in the PepperShop for a long time, starting with version 2.5.1.
  • Info: With the optional additional module ‘Datatrans Advanced Module’ the Datatrans hiddenMode can be used with credit card alias and ELV, so that card data do not have to be entered again with a new purchase. This module is subject to a fee and requires a PCI certification of the shop system as well as a valid SSL/TLS certificate.

This documentation and the PepperShop implementation refer to the Datatrans eCom Technical Implementation Guide For Payment APIs up to version 9.2.15.

Configuration

In order to use Datatrans with the PepperShop you must have a valid E-Com Starter or Professional contract with Datatrans. This also implies one or more mail order contracts with the credit card institutions themselves.

PepperShop basic settings

First we configure the basic settings in the PepperShop. For this you have to switch to the shop administration and go to shop settings → General settings → Payment methods. There you can store Datatrans details and control the payment types.

As an example, a screenshot of the section of this mask was inserted further below in Figure 1.

As you can see, you have to activate the electronic payment methods (e.g. credit cards). This example shows a preselection of options (VISA, PostFinance). Alternatively, you can use a generic name for all credit cards, e.g. by entering a name like ‘credit card’ in the first institute field.

Then activate all institute entries to be used and use Datatrans as handling.

Below you will find the Datatrans specific settings. Here you have to enter your Merchant ID (obtained from Datatrans and sometimes called Partner ID), if you have an E-Commerce and an additional Mailorder / Phone Order contract you have to use the Merchant ID of the E-Commerce contract.

The additional security element generated by Datatrans is inserted in the Sign / HMAC input field. This is a longer number (sign) or a 128 character long text. The security element must first be created in the Datatrans backoffice.

Figure 1: General Shop Settings

Here in our example we have disabled the Auto Settlement setting. The Auto Settlement ensures that incoming payments are not only authorized, but also booked immediately. This is important as it may help to avoid a late reservation fee from the acquiring partner. Ultimately, every shop owner must decide for himself whether he only wants to authorize or book immediately. In the case of an authorization, the amount can be subsequently corrected downwards in the Datatrans back office. This is used, for example, if you do not have certain goods in stock.

Datatrans UPP basic settings

Now you should also go to the Datatrans UPP administration. UPP stands for Universal Payment Page and describes the flexible payment input mask and its mechanisms.

The PepperShop offers an input help for the settings required there. In the shop administration go to Shop settings → General settings → Payment methods. In this mask at the point ‘Datatrans’ you simply click on the link Required data to fill in the UPP data.

Here you can see all the data required for UPP administration. At the top in the middle is the link to the UPP administration, which you should follow now. (Datatrans UPP Administration: https://payment.datatrans.biz/upp/)

Figure 2: UPP data in the UPP administration

Here we first select UPP administration above and then go to the UPP data. Figure 2 shows an example screenshot of the UPP mask from the Datatrans backoffice. We now see the following picture (without filled in data):

You can now copy the paths one-to-one from the PepperShop help text and paste them here. Please also note that the URL Post data format is set to ‘Data in Post Format’. (Info: The XML format did not offer the same functionality at the time of implementation and was therefore not implemented in the first place).

In the UPP Designer you can adjust the CI/CD according to the colors used in the shop.

Please make sure that no security elements are currently selected in the Security section (selection above). → If this is not the case, you first have to look at the advanced configuration.

Datatrans security default settings

If you are logged in to the UPP administration, you can access the configuration of the security elements for parameter transfer via the items UPP administration → Security.

The PepperShop supports all three security levels offered by Datatrans. You can conveniently enter the security element via the administration in the shop. We recommend using the HMAC key. To do this, you must activate the radio button on the lower security element and click on the ‘Generate new key’ button. A new value (128 characters) now appears to the left of it in the text input field. This setting is now saved by clicking on the ‘Confirm’ button at the bottom right. Please set the setting ‘Use another key for sign2’ to NOT.

Now you are asked to confirm this setting with the password.

Configuration of credit card type Preselection

Figure 3: Security settings (example with Security Level 2 active -- HMAC key)

The PepperShop offers two ways for customers to choose their credit card type (VISA, Mastercard, …):

Preselection in the PepperShop

With this variant, the customer is shown a preselection of possible credit card types below the checkout, when selecting the payment method in a dropdown menu next to the point ‘Credit card’. Alternatively, you can also display the individual payment types as your own payment types listed. An example:

Figure 4: Credit card selection with dropdown

Which cards you want to specify can be defined in the shop administration under shop settings → General settings → Payment methods. See Figure 1. Among others, the following texts can be used:

  • VISA
  • Eurocard/Mastercard or Mastercard
  • American Express
  • Diners Club
  • PostFinance or PostFinance Card
  • PayPal

Please pay attention to the upper/lower case, only the here mentioned terms will be recognized to create a credit card type preselection within the PepperShop or in the selection list.

A list of all names is displayed if you click [current configuration] in the Datatrans settings in “Shop settings/General settings/Payment methods”.

Note: If you pre-select a credit card type that is not enabled at Datatrans, you will be automatically routed to the error page when you enter the Datatrans payment entry window. This also happens if, for example, the sign is wrong, or you try to execute a transaction in an unsupported currency.

Selection of the specific payment methods

You can either display only a single point as payment type in the checkout for the purchasing customer, this is usually the default, if not hidden-UPP is used. Then the customer chooses e.g. ‘credit card’ and is forwarded to the Datatrans payment window. Here he first sees the payment methods available for selection and chooses one of them.

Advanced configuration

The most important Datatrans settings could be done comfortably via GUI. But if you want to make detailed settings, the PepperShop allows you to do so, too. The settings are made directly in the Datatrans configuration array (PHP) in the file {shopdir}/shop/datatransconfig.php. Here you can see an overview of the possible parameters:

<?php
// =============================================================================================
// DATATRANS AUTHORIZATION REQUEST VARIABLEN (please do not change order!)
// =============================================================================================
// Assign read data (1=>Login,3=>Password,5=>Account-ID) / Create configuration
$datatrans_config["login"] = $db_daten[3]; // Unique login name assigned by Datatrans // Not used at the moment
$datatrans_config["passwort"] = $db_daten[5]; // Unique password given by Datatrans // Not used at the moment
$datatrans_config["merchantId"] = $db_daten[1]; // Unique merchant ID assigned by Datatrans
$datatrans_config["currency"] = $waehrung; // Currency (Swiss Franc = CHF, Euro = EUR) / ISO-4217 compliant
$datatrans_config["language"] = $sprache; // If possible: Active language, otherwise default language.
$datatrans_config["successUrl"] = get_datatrans_success_url($close_iframe_param); // Success: Link to completion of the order
$datatrans_config["errorUrl"] = get_datatrans_error_url($close_iframe_param); // Error: Link to error message page
$datatrans_config["cancelUrl"] = get_datatrans_cancel_url($close_iframe_param); // abort -> link back to checkout
$datatrans_config["reqtype"] = $request_type; // Default = no
$datatrans_config["testOnly"] = 'no'; // Possibilities: 'yes' or 'no'. If = yes, the loopback test mode is switched on.
$datatrans_config["refno"] = substr($myReferenz_Nr.$trh_id,0,18); // PepperShop Order Reference Number + opt. Transaction Handler Reference
$datatrans_config["sign_simple"] = $signs_data["sign_simple"]; // If used in UPP Security (Level 1): Additional merchant identification
$datatrans_config["sign_hmac_md5"] = $signs_data["sign_hmac_md5"]; // If UPP Security (Level 2): Parameters are signed in HMAC Key (in Hex)
$datatrans_config["paymentmethod"] = get_datatrans_pmethod($Kreditkarten_Hersteller); // Pre-select KK, depending on handed over KK-manufacturer
$datatrans_config["pos_payment_type"] = get_datatrans_pos_payment_type($Kreditkarten_Hersteller); // Make PostFinance payment type preselection
$datatrans_config["useAlias"] = datatrans_check_alias($datatrans_config["paymentmethod"]); // Get alias Use
if (!defined('ADMIN_MODE') || ADMIN_MODE == false) $datatrans_config["hiddenMode"] = datatrans_check_hidden_mode(); // Get HiddenMode Use
$datatrans_config["uppMobileMode"] = $upp_mobile_mode; // "on" or not transferred for resizing to mobile screens
$datatrans_config["useTouchUI"] = 'auto'; // "yes", "auto", "no" - Touch Device?
// $datatrans_config["sign"] = ''; // Will first be compiled in datatrans_interface.php
// =============================================================================================
// TRANSACTIONSPROXY VARIABLEN (please do not change order!)
// =============================================================================================
$datatrans_config['proxy_go_to'] = 'https://'.DATATRANS_PAYMENT_HOST.'/upp/jsp/upStart.jsp'; // Script for comm. with Datatrans via UTF-8
$datatrans_config['proxy_charset'] = 'utf-8'; // character set which the transaction proxy should use (Datatrans requires UTF-8)
$datatrans_config['proxy_utf8_encode_vars'] = 'true'; // character set to be used by the transaction proxy (Datatrans requires UTF-8)
$datatrans_config['proxy_go_to'] = 'https://payment.datatrans.biz/upp/jsp/upStartIso.jsp'; // Script for comm. with Datatrans via ISO
// $datatrans_config['proxy_charset'] = 'iso-8859-1'; // character set which the transaction proxy should use
$datatrans_config['proxy_lang'] = $sprache; // language the transaction proxy should use
$datatrans_config['proxy_referencenr'] = $myReferenz_Nr; // Order reference number evaluated by transaction proxy
$datatrans_config['proxy_transaction_info'] = 'datatrans'; // string to describe the type of transaction
$datatrans_config['proxy_use_get_only'] = 'true'; // But we want to use all parameters passed via GET as POST first
$datatrans_config['proxy_block_get'] = 'true'; // We want to have a pure POST, not a GET/POST mix
$datatrans_config['proxy_connect_customer_and_order'] = 'true'; // We want the order to be connected to the customer (customermgmt), Attention: Only valid for payments in standard mode. Hidden-mode payments are never linked (since no TR proxy!)
$datatrans_config['proxy_onclose_back_to_kasse'] = 'false'; // If the popup window is closed, it will automatically go to the checkout - CAUTION!
// =============================================================================================
// PEPPERSHOP VARIABLEN (please do not change order!)
// =============================================================================================
$datatrans_config["randomNr"] = $zufallszahl; // PepperShop random number for this transaction
$datatrans_config["check_random_nr"] = false; // If = true, check random number (is obsolete, please use HMAC!)
$datatrans_config["check_trusted_hosts"] = false; // If = true, the sender of the PostURL messages is checked against an IP whitelist

Security

Datatrans offers different security levels, which have to be requested from you:

  • Security level 0: No additional security attributes. But the PepperShop already offers some checks: Sender host comparison, random number comparison, hidden post message (not recommended!)
  • Security Level 1: In addition, a constant is passed. This is agreed in the UPP administration → Security as sign and can be specified in the shop administration in the general shop settings in the Datatrans settings.
  • Security Level 2: Here, important attributes of the authorization are provided with an MD5 hash (your HMAC key) and sent along, so that a change in the data (Man-In-The-Middle attack) would be recognized immediately. The HMAC key to create a HMAC-MD5 encryption can be obtained from the UPP administration → Security. Info: The PepperShop can only handle one key at the moment, please do not choose two different keys. (Level 2 is recommended by us)

Info: More details about the security levels can be found in the manual ‘Datatrans eCom Technical Implementation Guide For Universal Payment Page (UPP)’ v.8.13 on pages 30ff.

Assign payments

If you now buy via credit card (via Datatrans) in the PepperShop, the administrator receives an overview of the order in the customer management. Here (and not in the e-mail) the Datatrans details are displayed. The way is: Shop administration → Customers/orders → Customer management → Customer search → Letter of customer name → Customer → Orders → Open latest credit card order, example:

Figure 5: Extract from a Datatrans order in customer management

It is important that the payment received can also be assigned to the payment received in the Datatrans back office. As you can see, every successful Datatrans payment is accompanied by a so-called payment info. This consists of three parts:

  • ECA = Eurocard/MasterCard and stands for the credit card used. Possibilities:
    • VIS = VISA
    • ECA = Eurocard/Mastercard or Mastercard (MPW = MasterPass Wallet)
    • AMX = American Express
    • DIN = Diners Club
    • POS = PostFinance (PostFinance Card and PostFinance e-finance)
    • PAP = PayPal
    • TWI = TWINT Wallet
    • PSC = Paysafecard
    • DIB = Immediate bank transfer
    • PFC = PostFinance Card (PEF = PostFinance e-finance)
    • ESY = Swisscom Easypay / Natel Pay (only works with Auto-Settlement = switched on)

  • The second number stands for the Datatrans Authorization Code.
  • The third number is the Aquirer Authorization Code and can be found in the Backoffice (Datatrans Backoffice: http://payment.datatrans.biz/) under Authorization Code:

Figure 6: Extract from the Datatrans Pronto-Backoffice

Of course, the reference number from the PepperShop described also helps. If the transaction handler is activated, these are the first characters up to the first underscore (_). The transaction handler is controlled by a configuration directive. At the top of the {shopdir}/shop/config.inc.php file:

<?php
define('DATATRANS_USE_TRANSACTION_HANDLER', true); // If the Datatrans connection should use the Transaction Handler (Unique Reference No.)

Logging

We strongly recommend that you activate the transaction logging of the PepperShop. In this way you always keep an eye on everything, even in problematic situations.

The {shopdir}/shop/config.inc.php file contains the following two configuration directives:

<?php
define('DATATRANS_LOG','datatrans.log'); // Name of the logging, default = datatrans.log
define('DATATRANS_LOG_CALLS',false); // Should all Datatrans calls be logged?, default = false

LOG_TRANSACTIONS should be set to (boolean) true if you want to enable transaction logging. We recommend this, but could not set the default setting to true, because otherwise large logs would have been created for many users without their knowledge.

Log Viewer

In case of problems and also otherwise one should consult the Log-Viewer every now and then (PepperShop Professional and Enterprise versions). To install it you can click on ‘Modules’ in the shop administration. Here go to the module administration and install the Log Viewer (left side).

If you now leave the module administration again, you will see a new button for the log viewer. Normally and with transaction logging switched off, no log files should be created, but otherwise you can see the logs there.

PepperShop Basic users must manually evaluate the logs in the log directory {shopdir}/shop/Admin/log.

Transactions

A transaction always consists of two parts: Transaction initiation (transaction_initiate) and transaction completion (transaction_complete). Before and immediately after the database operation, brands are set in the transaction log and the order changes its status. The shown transaction changes its status from 0001 (open order) to 1000 (open order, after accepting the terms and conditions when using an external payment service provider). Per transaction part (initiate, complete) there are always two log entries, which are each titled x_y_start and x_y_done.

Figure 7: Specially highlighted order after accepting the terms and conditions

After the transation completion, the order status changes from 1000 to 2000 (complete).

Figure 8: Order process and back office processes + order status

A rollback back to 0001 means, for example, that a transaction could not be completed correctly (for example, if an error occurred during processing of the externally linked payment).

Transactions with the status 1000 are already highlighted in the customer management.

In this way it is also possible to track orders that have been unintentionally interrupted by the user.

Please note the following difference: ‘AGBs accepted, order still open’ (status 1000) means that the customer has opened the Datatrans popup and wants to make the payment. However, this has not yet done and thus also has not yet transferred any money. These orders should be deleted if you are over a day old.

Orders with the status 2000 ‘GTC accepted, transaction completed’, however, are completed and paid orders, for which for some reason the order completion could not be carried out with the mail dispatch. You should complete these orders manually and contact the customer.

Next to it you can see a sample excerpt of a transaction log:

Transaction handler

In addition to the transactions, the transaction status history logged by the PepperShop transaction handler can also be seen in the detailed view of an order in the customer management of the shop administration.

Figure 9: Extract from a transaction log

Recommendation

We recommend the use of a valid SSL/TLS certificate. This prevents many browsers from displaying information when redirecting from the Datatrans Payment Terminal that you are now leaving an encrypted page. This is indicated by the browser when you jump back to the unencrypted shop after the payment process, so that “Thank you very much for your purchase” can be displayed there.

About ‘Datatrans Advanced Module’

  • hiddenMode-UPP: Here the shop operator enters all required credit card data in the shop itself. This requires a valid SSL server certificate and PCI certification.
  • Alias: If Alias has been activated by Datatrans and the Datatrans Advanced module is used, the customer can pay for subsequent purchases without having to re-enter his credit card details each time. This simplifies payment.

Contact details

Datatrans AG
Stadelhoferstrasse 33
CH-8001 Zurich
Phone +41 (0)44 256 81 91
Fax +41 (0)44 256 81 98
info@datatrans.ch
http://www.datatrans.ch/

🌶️
🔥
🌶️