No momento, esta página não está disponível em português
Classic-integration icon

HMAC signature calculation

Hosted Payment Pages are no longer available

To accept payments through an Adyen-hosted page, use our Hosted Checkout.

This page is for the classic Hosted Payment Pages (HPP) integration, which has reached end-of-life. We are no longer processing transactions though HPP.

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.

Signatures can also be used to add an extra layer of security for webhooks. However, the calculation for this functionality is different. For details, refer to the Signing webhooks with HMAC guide.

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:

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

Don't use this example key for your real integration with Adyen.

1. Sort the key-value pairs by key.

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

Key Value
currencyCode EUR
merchantAccount YOUR_MERCHANT_ACCOUNT
merchantReference paymentTest\:143522\\64\\39255
paymentAmount 1995
sessionValidity 2018-07-25T10\:31\:06Z
shipBeforeDate 2018-07-30
shopperLocale en_GB
skinCode X7hsNDWp
  1. 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
  1. 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.

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

You need the Merchant Technical Integrator role to be able to see the page in your 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.