HMAC signature calculation

To ensure authenticity and data integrity of incoming requests Adyen requires these requests to be signed. This signature is based on a Hash-based Message Authentication Code (HMAC) calculated using a request's key-value pairs and a secret key, which is known only to you and Adyen. 

Before sending a request to Adyen, you calculate a signature and add it as a request parameter. When a request comes in, Adyen calculates the same signature based on the received key-value pairs and the secret key stored by Adyen. By verifying that both signatures are equal, Adyen ensures that the request is not tampered.

Similarly, you can validate responses from Adyen by calculating the corresponding signature and comparing it with the signature in the response.

Getting HMAC keys

You need to generate your secret HMAC keys to use them for signature calculation. To obtain these keys for the test and live platform, follow the steps below:

1. Log in to your Customer Area using your company-level account.

2. From the main menu, select Settings > Skins.

3. Select an existing skin from the List tab or create a new skin by switching to the New tab.

4. Click Generate new HMAC key both for the Test platform and Live platform. Then copy new keys and store them in a secure place in your system to access these values later.
   

5. Provide a description for this skin.

6. To save the skin click Create New Skin on Test at the page bottom.

Implementing signature calculation

In this tutorial, we use the following HMAC key and key-value pairs as an example.

Sample HMAC key:

44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056

Sample key-value pairs:

1. Sort the key-value pairs by key.

2. Replace null values with an empty string ("") and escape the following characters in the value of each pair:

• "\" (backslash) as "\\"
• ":" (colon) as "\:"

The table below reflects the sorting and escaping steps.

3. Concatenate the key names, first, followed by the values. Use a colon (":") to delimit the key names and values to obtain the signing string.

The signing string below shows the concatenated and delimited key-value pairs.

currencyCode:merchantAccount:merchantReference:paymentAmount:sessionValidity:shipBeforeDate:shopperLocale:skinCode:EUR:YOUR_MERCHANT_ACCOUNT:paymentTest\:143522\\64\\39255:1995:2018-07-25T10\:31\:06Z:2018-07-30:en_GB:X7hsNDWp

4. Convert the HMAC key to the binary representation. Note that the HMAC key is considered as hexadecimal value.

5. Calculate the HMAC with the signing string, in binary representation given the UTF-8 charset, using the cryptographic hash function SHA-256.

6. Encode the result using the Base64 encoding scheme to obtain the signature.

The signature calculated, for example, key-value pairs and HMAC key is:

8SFtIc6zQlswxAZqDKXL+BpRmlDvIWyjOwU8wdl0zK4=

Testing a signature

You can check your signature calculation by constructing a request URL from the key-value pairs and a check HMAC endpoint:
https://ca-test.adyen.com/ca/ca/skin/checkhmac.shtml

To make the request, you have to be signed into your merchant account, as the endpoint is a part of the Customer Area.

Note that for the test to work you also need to supply your merchant account and a skin code associated with it.

Supply the signature in the merchantSig field, and the parameters have to be URL-encoded.

Optionally, to compare your signing string with the string that Adyen calculates from the supplied key-value pairs, you can submit the signingString field value in addition to the standard payment fields.