Guides

Sign

Adding a signature was an option we offered to merchants to add further security to their payments. For this, the sign parameter contained a signature that was either static or dynamic. This signature was mandatory prior to our JSON API, if basic authentication was not used.

📘

Sign is deprecated!

Please note that Sign is deprecated and relies on our legacy API. The sign is not required in our new integration.

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 (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();
    }
}

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”.

📘

Parameter sign2 only in success responses

Please note that the parameter sign2 is returned only for successful transactions.

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();
    }
}

Updated about 1 year ago