Search

Are you looking for test card numbers?

Would you like to contact support?

Developer-resource icon

Verify HMAC signatures

Verify the integrity of notifications using HMAC signatures.

To protect your server from unauthorised notifications, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. After you enable HMAC signatures, each notification will include a signature calculated using a secret HMAC key and a payload from the notification. By verifying this signature, you confirm that the notification was sent by Adyen, and was not modified during transmission.

To verify HMAC signatures, you can either:

Enable HMAC signatures

To enable HMAC signed notifications, it is enough to generate a secret HMAC key in your Customer Area. The secret key is linked to a Standard Notification endpoint. If you have multiple endpoints for receiving notifications, you need to generate an HMAC key for each of them.

You also need to generate a new HMAC key when you switch from test to live.

To start receiving HMAC signed notifications:

  1. Log in to your Customer Area. If you have set up notifications at the merchant level, switch to your merchant account.
  2. Go to SettingsServer Communication.
  3. Find the Standard Notification endpoint for which you want to enable HMAC, and click Edit & Test.
  4. Under Additional settings, click Generate New HMAC key.
  5. Securely store the HMAC key in your system - you won't be able to restore it later.
  6. Click Save Configuration.

The HMAC key will now be used to sign notifications that we send to your server. The signature is
included in the additionalData field:

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "hmacSignature":"+JWKfq4ynALK+FFzGgHnp1jSMQJMBJeb87dlph24sXw="
            },
          ...
         }
      }
   ]
}

If you generate a new HMAC key, it might take some time to propagate this in our infrastructure, so make sure that you can still accept notifications signed with your previous HMAC key for some time.

Verify using our libraries

You can verify signatures using our:

String hmacKey = "YOUR_HMAC_KEY";
// YOUR_HMAC_KEY from the Customer Area
String notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
HMACValidator hmacValidator = new HMACValidator();
NotificationHandler notificationHandler = new NotificationHandler();
NotificationRequest notificationRequest = notificationHandler.handleNotificationJson(notificationRequestJson);
// Handling multiple notificationRequests
List<NotificationRequestItem> notificationRequestItems = notificationRequest.getNotificationItems();
for ( NotificationRequestItem notificationRequestItem : notificationRequestItems ) {
    if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) {
        // Handle the notification
        String eventCode = notificationRequestItem.getEventCode();
        // Process the notification based on the eventCode
    } else {
        // Non valid NotificationRequest
        System.out.print("Non valid NotificationRequest");
    }
}
$hmacKey = "YOUR_HMAC_KEY";
// YOUR_HMAC_KEY from the Customer Area
$jsonRequest = "NOTIFICATION_REQUEST_JSON";
$notificationRequest = json_decode($jsonRequest, true);

$hmac = new \Adyen\Util\HmacSignature();
foreach ( $notificationRequest["notificationItems"] as $notificationRequestItem ) {
  $params = $notificationRequestItem["NotificationRequestItem"];
  if ( $hmac->isValidNotificationHMAC($hmacKey, $params) ) {
    $eventcode = $params['eventCode'];
    print_r($eventcode);
    // Process the notification based on the eventCode
  } else {
    // Non valid NotificationRequest
  }
}
string hmacKey = "YOUR_HMAC_KEY";
// YOUR_HMAC_KEY from the Customer Area
string notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
var hmacValidator = new HmacValidator();
var notificationHandler = new NotificationHandler();
var handleNotificationRequest = notificationHandler.HandleNotificationRequest(notificationRequestJson);
// Handling multiple notificationRequests
List<NotificationRequestItemContainer> notificationRequestItemContainers = handleNotificationRequest.NotificationItemContainer;
foreach ( var notificationRequestItemContainer in notificationRequestItemContainers ) {
    var notificationItem = notificationRequestItemContainer.NotificationItem;
    if ( hmacValidator.IsValidHmac(notificationItem, hmacKey) ) {
        string eventCode = notificationItem.EventCode;
        // Process the notification based on the eventCode
    } else {
        // Non valid NotificationRequest
    }
}
const { hmacValidator } = require('@adyen/api-library');
const hmacKey = "YOUR_HMAC_KEY";
// YOUR_HMAC_KEY from the Customer Area
const notificationRequest = NOTIFICATION_REQUEST_JSON; // Notification Request JSON
const notificationRequestItems = notificationRequest.notificationItems
notificationRequestItems.forEach(function(notificationRequest) {
    if( validator.validateHMAC(notificationRequestItem, hmacKey) ) {
        const eventCode = notificationRequestItem.eventCode;
        // Process the notification based on the eventCode
    } else {
        // Non valid NotificationRequest
        console.log("Non valid NotificationRequest");
    }
});

Verify using your own solution

To build your own solution for verifying HMAC signatures, follow these steps:

Step 1: Construct the payload

Concatenate the following values from the notification, in the given order:

Key Value
pspReference 7914073381342284
originalReference
merchantAccountCode TestMerchant
merchantReference TestPayment-1407325143704
value 1130
currency EUR
eventCode AUTHORISATION
success true

Escape the following characters in each value:

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

Assign an empty string to any fields that are empty, and use a colon (":") to delimit the values.

For the above values, with an empty originalReference, you get:

7914073381342284::TestMerchant:TestPayment-1407325143704:1130:EUR:AUTHORISATION:true

Step 2: Calculate the HMAC signature

  1. Calculate an HMAC using:

    • The SHA256 function.
    • Binary representation of the payload that you constructed in Step 1, given the UTF-8 charset.
    • Binary representation of the HMAC key, given the UTF-8 charset.
  2. To get the final signature, Base64-encode the result.

Step 3: Compare signatures

If the signature that you calculated in Step 2 matches the hmacSignature that you received, you'll know that the notification was sent by Adyen and was not modified during transmission.

Example

Sample HMAC key:

44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056

Sample notification signed using the above HMAC key:


{  
   "live":"false",
   "notificationItems":[  
      {  
         "NotificationRequestItem":{  
            "additionalData":{  
               "hmacSignature":"coqCmt/IZ4E3CzPvMY8zTjQVL5hYJUiBRg8UU+iCWo0="
            },
            "amount":{  
               "value":1130,
               "currency":"EUR"
            },
            "pspReference":"7914073381342284",
            "eventCode":"AUTHORISATION",
            "eventDate":"2019-05-06T17:15:34.121+02:00",
            "merchantAccountCode":"TestMerchant",
            "operations":[  
               "CANCEL",
               "CAPTURE",
               "REFUND"
            ],
            "merchantReference":"TestPayment-1407325143704",
            "paymentMethod":"visa",
            "success":"true"
         }
      }
   ]
}

See also