The below steps describe a basic way of how a transaction flow with Datatrans can work:

• Send all the needed parameters with a secure server to server call to Datatrans and retrieve a transactionId.
• Redirect the customers browser to the Payment Page by using the returned transactionId.
  • When using the Redirect Mode, The URL where the customers browser needs to be redirected to looks like:

    https://pay.sandbox.datatrans.com/v1/start/transactionId

  • When using the Lightbox Mode, make sure to use the latest version of the JS library:

    <script src="https://pay.sandbox.datatrans.com/upp/payment/js/datatrans-2.0.0.js">

    payButton.onclick = function() {
      Datatrans.startPayment({
        transactionId:  "transactionId"
      });
    };

• The customer enters their payment details and presses the Pay button.
• The transactionId and other important parameters will be sent to your Webhook URL. Store them in your DB. In addition, the transactionId will also be sent to your success/cancel/error URLs.
• The browser will be redirected to the success/cancel/error page.
• Use the transactionId to perform different actions like cancel, credit and settle

For SecureFields please refer to the server to server SecureFields init operation.

For mutable API calls we allow to pass a unique value with the Idempotency-Key header. Those requests can then safely be retried in case a network error happens. For example:

curl -i -u 1100007283:hl2ROSRqCvjnDVRK 'https://api.sandbox.datatrans.com/v1/transactions' \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -H 'Idempotency-Key: e75d621b-0e56-4b71-b889-1acec3e9d867' \
    -d '{
    "refno" : "58b389331dad",
    "amount" : 1000,
    "currency" : "CHF",
    "paymentMethod" : [ "VIS", "ECA", "PAP" ],
    "option" : {
       "createAlias" : true
    }
}'

Authentication to the APIs is performed via HTTP basic authentication. Provide your merchantId as the basic authentication username value. To get the password, login to Webadmin and enable server to server security under UPP Administration > Security.

Create a base64 encoded value of merchantId and password (most HTTP clients are able to handle the base64 encoding automatically) and submit the Authorization header with each request. For example:

base64(merchantId:password) = MTAwMDAxMTAxMTpYMWVXNmkjJA==

Authorization: Basic MTAwMDAxMTAxMTpYMWVXNmkjJA==

All API requests must be done over HTTPS with TLS >= 1.2.

Datatrans uses HTTP response codes to indicate if an API call was successful or resulted in a failure. HTTP 2xx status codes indicate a successful API call whereas HTTP 4xx status codes indicate client errors or if something with the transaction went wrong (for example a decline). In rare cases HTTP 5xx status codes are returned. Those indicate errors on Datatrans side.

Sample HTTP 400 error response payload if a property has a wrong value

{
  "error" : {
    "code" : "INVALID_PROPERTY",
    "message" : "init.initRequest.currency The given currency does not have the right format"
  }
}

After each authorization Datatrans tries to call the configured Webhook (POST) URL. The Webhook URL can be configured within the Webadmin Tool. The Webhook payload is the exact same as for the Status API.

Add an additional security layer by signing our webhooks. To get your HMAC key (sign2), login to our dashboard and navigate to the Security settings in your merchant configuration. If not already done, select the checkbox Use another key for sign2 generation. Datatrans will use this key to calculate a signature. Once the checkbox is active, we will generate a new HMAC key and add two parameters within the HTTP request header Datatrans-Signature: A unique timestamp and the expected signature. For example:

Datatrans-Signature: t=1559303131511,s0=33819a1220fd8e38fc5bad3f57ef31095fac0deb38c001ba347e694f48ffe2fc

To calculate the expected signature, concatenate the timestamp as a string with the webhook payload. Convert the resulting string to bytes and finally create a signature with your HMAC key using SHA256. Finally, compare your calculation to the expected signature s0. Examples:

Java

// hex bytes of the key
byte[] key = Hex.decodeHex(key);

// Create sign with timestamp and payload
String algorithm = "HmacSha256";
SecretKeySpec macKey = new SecretKeySpec(key, algorithm);
Mac mac = Mac.getInstance(algorithm);
mac.init(macKey);
mac.update(String.valueOf(timestamp).getBytes());
byte[] result = mac.doFinal(payload.getBytes());
String sign = Hex.encodeHexString(result);

Python

# hex bytes of the key
key_hex_bytes = bytes.fromhex(key)

# Create sign with timestamp and payload
sign = hmac.new(key_hex_bytes, bytes(str(timestamp) + payload, 'utf-8'), hashlib.sha256)

If the value of sign is equal to s0 from the Datatrans-Signature header, the webhook payload is valid and was not tampered.