The developer.datatrans.com Developer Hub

Welcome to the developer.datatrans.com developer hub. You'll find comprehensive guides and documentation to help you start working with developer.datatrans.com as quickly as possible, as well as support if you get stuck. Let's jump right in!

Sign

Digital signature

Sign Overview

Whenever you use one of our APIs please make sure to submit the sign parameter. This is mandatory and needs to be done for both, the Browser APIs as well as for the Server to Server APIs if server to server security is not used.

Sign Calculation

The sign calculation is only needed if you chose to send a dynamic sign to our systems. If you chose to send a simple sign, the calculation will not be required. We recommend however to use a dynamic sign for all your transactions to ensure higher security standards.

Here's how the digital signature (value of parameter sign) can be calculated:

  1. Translate HMAC key from hex to byte format
  2. Create string to be signed by concatenating of parameters in exactly this order and without separators:
    • aliasCC (only if parameter aliasCC is used in payment request)
    • merchantId
    • amount
    • currency
    • refno

Resulting String (example): 424242VMKSNZ42421000011011850CHF91827364

  1. Sign the string using HMAC-SHA-256 procedure based on merchant’s HMAC key
  2. Translate signature from byte to hex format and associate it as value with parameter sign
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
 
public class SignGenerator {
 
   /**
     * Generates HMAC-SHA256 signature and returns it as hexadecimal string
     *
     * @param aliasCC - aliasCC or 'noAlias' if aliasCC is not available
     * @param hexaKey - merchant's hmac key obtained from web admin tool
     * @param merchantId - merchant's id
     * @param amount - amount in cents
     * @param currency - three-letter currency code
     * @param refno - reference number
     * @return hexa HMAC-SHA256 signature (lowercase)
     *
     * @throws IllegalArgumentException
     * @throws NoSuchAlgorithmException
     * @throws InvalidKeyException
     */
    public static String getHexaSHA256Signature(String aliasCC, String hexaKey, String merchantId,
                                                String amount, String currency, String refno)
            throws IllegalArgumentException, NoSuchAlgorithmException, InvalidKeyException {

        if ( hexaKey == null )
            throw new IllegalArgumentException("null key");

        byte[] key = DatatypeConverter.parseHexBinary(hexaKey);
        SecretKeySpec macKey = new SecretKeySpec(key, "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(macKey);
        String valueToSign = aliasCC.trim() + merchantId.trim() + amount.trim() + currency.trim() + refno.trim();
        byte[] result = mac.doFinal(valueToSign.getBytes());
        return DatatypeConverter.printHexBinary( result ).toLowerCase();
    }
}

Sign2 calculation

This signature is passed back to the merchant in parameter sign2, which is created in the same way as the parameter sign except that the signed string contains the parameter uppTransactionId instead of the reference number refno. For an even higher security level, it’s also possible to generate an alternative key for the sign2 parameter. With this feature sign2 is created with a different key. To enable it, the option “Use another key for sign2 generation” has to be activated in our Webadmin Tool in the menu “Security”.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
 
public class Sign2Generator {
 
   /**
     * Generates HMAC-SHA256 signature and returns it as hexadecimal string
     *
     * @param aliasCC - aliasCC or 'noAlias' if aliasCC is not available
     * @param hexaKey - merchant's hmac key obtained from web admin tool
     * @param merchantId - merchant's id
     * @param amount - amount in cents
     * @param currency - three-letter currency code
     * @param transactionId - the transactionid generated by Datatrans
     * @return hexa HMAC-SHA256 signature (lowercase)
     *
     * @throws IllegalArgumentException
     * @throws NoSuchAlgorithmException
     * @throws InvalidKeyException
     */
    public static String getHexaSHA256Signature(String aliasCC, String hexaKey, String merchantId,
                                                String amount, String currency, String transactionId)
            throws IllegalArgumentException, NoSuchAlgorithmException, InvalidKeyException {

        if ( hexaKey == null )
            throw new IllegalArgumentException("null key");

        byte[] key = DatatypeConverter.parseHexBinary(hexaKey);
        SecretKeySpec macKey = new SecretKeySpec(key, "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(macKey);
        String valueToSign = aliasCC.trim() + merchantId.trim() + amount.trim() + currency.trim() + transactionId.trim();
        byte[] result = mac.doFinal(valueToSign.getBytes());
        return DatatypeConverter.printHexBinary( result ).toLowerCase();
    }
}

Sign


Digital signature

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.