Transaction hash upgrade guide

Note: This guide documents how to use the transaction hash with the Authorize.net API. Users of the legacy AIM connection method should refer to the AIM Guide, pages 57-59, for instructions. Users of the legacy SIM and DPM connection methods should refer to the SIM Guide, pages 73-75.

Authorize.net is phasing out the MD5 based transHash element in favor of the SHA-512 based transHashSHA2. The setting in the Merchant Interface which controls the MD5 Hash option will be removed by the end of January 2019, and the transHash element will stop returning values at a later date to be determined.

When you receive a transaction response from Authorize.net, it includes the transHashSHA2 element.  transHashSHA2 contains the HMAC-SHA512 hash that Authorize.net generated for the transaction. To use it, construct a HMAC-SHA512 hash and compare your hash result with transHashSHA2. If the two values match, the transaction response came from Authorize.net.

Note: The value of transHashSHA2 will be null if you do not generate the Signature Key first.

Note: All Authorize.net values, including the Signature Key and the transHashSHA2 element, use ISO 8859-1 characters. Using Unicode instead of ISO 8859-1 may cause hash mismatches.

To use the Signature Key to validate the value of transHashSHA2:
 

1. Step 1. Generate a Signature Key and store it in a secure location on your server.
   
   
2. Step 2. Convert the Signature Key into a byte array.
   
   
3. Step 3. Create a message string that starts with a caret ( ^ ), followed by the following three fields delimited by carets, and terminated with another caret:
   
   •    The API Login ID that you send in createTransactionRequest in the name element.
   
   •    The transaction ID that we send in createTransactionResponse in the transId element.
   
   •    The transaction amount that we send in createTransactionResponse in the amount element.
   
   For example, if your API Login ID is "ANet123", the value of transId is "20987654321", and the value of amount is "9.99", the message string would look like this:
   
   ^ANet123^20987654321^9.99^
      
4. Step 4. Use HMAC-SHA512 to hash the byte array form of the Signature Key from Step 2 with the message string from Step 3.
   
   
5. Step 5. Compare the value of transHashSHA2 with the output from the HMAC-SHA512 hash mentioned in Step 4.
    

For C# users, Authorize.net provides the following code for converting the Signature Key into a byte array and calculating the HMAC-SHA512 hash.

            public string HMACSHA512(string key, string textToHash)
{
    if (string.IsNullOrEmpty(key))
        throw new ArgumentNullException("HMACSHA512: key", "Parameter cannot be empty.");
    if (string.IsNullOrEmpty(textToHash))
        throw new ArgumentNullException("HMACSHA512: textToHash", "Parameter cannot be empty.");
    if (key.Length % 2 != 0 || key.Trim().Length < 2)
    {
        throw new ArgumentNullException("HMACSHA512: key", "Parameter cannot be odd or less than 2 characters.");
    }
    try
    {
        byte[] k = Enumerable.Range(0, key.Length)
                    .Where(x => x % 2 == 0)
                    .Select(x => Convert.ToByte(key.Substring(x, 2), 16))
                    .ToArray();
        HMACSHA512 hmac = new HMACSHA512(k);
        byte[] HashedValue = hmac.ComputeHash((new System.Text.ASCIIEncoding()).GetBytes(textToHash));
        return BitConverter.ToString(HashedValue).Replace("-", string.Empty);
    }
    catch (Exception ex)
    {
        throw new Exception("HMACSHA512: " + ex.Message);
    }
}