Guides
These docs are for v1.0.1. Click to read the latest docs for v2.1.0.

Sign

Sign Overview

Whenever you use one of our APIs, please submit the sign parameter. The sign parameter is mandatory and needs to be done for both the Browser APIs and the Server to Server APIs if server to server security is not used. You have the option to send a static sign or dynamic sign within your requests.

Dynamic Sign Calculation

The dynamic sign calculation below is required to enhance your transactions' security. Here's how the digital signature - the value of the parameter sign - can be calculated:

  1. Translate your HMAC key from hex to byte
  2. Create a string by concatenating the parameters below in the following order and without separators:
    • aliasCC (only required if the parameter aliasCC is used in your payment request)
    • merchantId
    • amount
    • currency
    • refno

Resulting String (example): 424242VMKSNZ42421000011011850CHF91827364

  1. Sign the string with HMAC-SHA-256 together with your HMAC key
  2. Translate the signature from byte to hex format
  3. This value is what you need to associate with the parameter sign in your requests
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 (only if parameter aliasCC is used in payment request)
     * @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();
    }
}

Additional Sign: sign2

This additional sign can be sent back in our response within the parameter sign2. It is created the same way as the dynamic sign with one exception: The concatenated string contains the value of uppTransactionId instead of the reference value refno. You have the option to define an alternative HMAC key for the sign2 parameter - this enhances your security as the signature is created with a different key. To use a different key for sign2, the option “Use another key for sign2 generation” has to be activated in our Webadmin Tool in the menu “Security”.

🚧

Sign2 only returned for successful transactions

The parameter sign2 is only returned for successful transactions to your successUrl and webhook. If you require a signature to be also passed in cancel and error cases, you will need to pass a new custom parameter in your request.

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 (only if parameter aliasCC is used in payment request)
     * @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();
    }
}

Further measures to enhance your security

If required by your project or company policies, you have the option to add further security measures. We suggest the following:

  • Add a secret static signature to your webhooks. We pass the signature in our webhooks to your server: webhookUrl?param1=value1
  • Make use of IP Whitelisting. You can refer to the IP Whitelisting section of our docs.

Updated almost 2 years ago