Do I need to upgrade my transaction fingerprint from HMAC-MD5 to HMAC-SHA512, and how?
You will first need to generate a Signature Key.
To generate a Signature Key:
- Log into the Merchant Interface at https://account.authorize.net.
- Click Account from the main toolbar.
- Click Settings from the menu on the left.
- Click API Credentials & Keys from the General Security Settings section.
- Under Create New Key(s), enter the answer to your Secret Question.
- Select the New Signature Key radio button.
- When obtaining a new Signature Key, you may choose to immediately disable the old Signature Key by clicking on the box titled, Disable Old Signature Key Immediately. If you have current software installations, do not check this box unless you need to cease immediately all payment processing that uses the Signature Key.
- Click Submit.
The construction of the HMAC-SHA512 hash is similar to the HMAC-MD5 hash. In particular, the input to be hashed is built from these values, in order, and separated by carets ("^"):
- The API Login ID (
- The unique merchant-generated sequence number (
- The transaction's timestamp in UNIX Epoch time, i.e. how many seconds have passed since Midnight UTC on January 1, 1970 (
- The transaction amount (
- The currency code (
x_currency_code), which should be blank if no currency code is submitted.
For example, if we presume an API Login ID of "authnettest", a sequence number of "789", a timestamp of "67897654," an amount of "10.50", and no currency code, the hash input would look like this:
If a currency code of "USD" were submitted, the hash input would look like this:
You would then hash this input with the HMAC-SHA512 algorithm, using the binary-encoded Signature Key as the HMAC key.
The resulting hash should be submitted to us as
x_fp_hash, just as you do with the HMAC-MD5 hash. We will know which hashing algorithm you used, by the size of the value for
All existing Response Reason Codes that indicate issues with the transaction fingerprint, will apply for the HMAC-SHA512 version as well as the legacy HMAC-MD5 version. Specifically, you may see these errors:
- RRC 97, indicating that the transaction fingerprint has expired;
- RRC 98, indicating that the transaction fingerprint has already been used;
- RRC 99, indicating a mismatch between the transaction fingerprint you submitted, and the fingerprint we expected;
- RRC 103, which is caused when the transaction fingerprint is generally invalid.
The Wikipedia entry on HMAC includes links to HMAC implementations in various scripting languages and frameworks.