Guides

Notification Hashing

Suggest Edits

When sending you a notification we will include a field hashCode in the notification payload. The value in this field is a hash of the notification content that can be used to verify that key fields in the notification payload have not been tampered with. Additionally, this allows you to confirm that the notification has been sent by BR-DGE.

When you receive a notification from BR-DGE you should create your own version of the hash following this process, then check that it matches the hashCode included in the original notification payload.

The following hashing process requires that you know your "shared secret". If you have notifications enabled in your retail channel(s) then you will have already set a "shared secret". If you are unsure of what this value is then please contact support.

The structure of notifications changes depending on the notification type. The following examples show the different structures you can expect. The full notification schemas can be viewed by checking out the "Callbacks" section at the bottom of each endpoint in the BR-DGE REST API.

{
  "code": "1000",
  "hashCode": "6TqCHicL7vJOeIxP10mKU9ECsmyUDaBNiB7CNMCMbgM=",
  "id": "171e808b-5998-40a7-a559-6cbe04c8c3cc",
  "merchantAccountId": "67398835-6ae6-4931-b046-2def568fe10a",
  "message": "Approved",
  "psp": {
    "message": "{\"id\":\"evt_tn5nq7xpqddexjudyfyhrst...}",
    "name": "Checkout.com",
    "transactionId": "pay_vxhcyge7pgzebfuwe34fglvucy"
  },
  "status": "CAPTURED",
  "type": "payment"
}

{
  "type": "token.network.metadataUpdate",
  "merchantAccountId": "aadf8010-4df3-49c6-96c0-9f175f60ef36",
  "code": "9003",
  "message": "Notification: Network Token metadata has been updated.",
  "hashCode": "90c3b3881074021383c8679f0232580f7b96cebacab77517fc4b479e6d977b06",
  "token": "c2fcf424-d7df-4b8b-aa98-3a60ce990d7c",
  "customerId": "customer-1234",
  "networkToken": {
    "token": "WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK",
    "status": "ACTIVE",
    "issuer": "VISA",
    "isCardArtUpdated": true,
    "paymentAccountReference": "V00asd62"
  }
}

{
  "type": "token.psp.statusChange",
  "merchantAccountId": "aadf8010-4df3-49c6-96c0-9f175f60ef36",
  "code": "1000",
  "message": "PSP Token Provisioned",
  "psp": {
    "name": "Checkout.com",
    "tokenId": "src_bacn2jgeqsuuzhkbwkbi7uvelq",
    "pspCardFingerprint": "6210AB060C8DA8E247908ACD7E0155E32D3ECA6E243831FC418B978DE3B11A71",
    "status": "ACTIVE"
  },
  "token": "5eeb93bb-d914-4b08-9006-37502f1f5a3f",
  "hashCode": "iJVhfczfW/5hAh7ttjfs8FtuRSGodhSRfNsCpzR3f9k="
}

How to generate the hashcode

Generating the hashCode requires you to follow the below steps in the correct order. These steps must be followed exactly, otherwise the output will not match the hash sent by BR-DGE.

  • Concatenate the relevant fields into a single string
  • Convert the result of the string concatenation into bytes
  • Generate a SHA-256 hash of the bytes
  • Encode the SHA-256 hash into Base64 - The output is your calculated hashCode

The below example shows how you can generate a hashCode using JavaScript.

📘

Each notification type will contain different fields.
If a field is not present in the notification payload it should be treated as an empty string

//Concatenate the notification fields & append your notification shared secret

const fields = notification.type
+ notification.merchantAccountId
+ notification.id
+ notification.code
+ notification.message
+ notification.status
+ notification.token
+ notification.psp.message
+ notification.psp.name
+ notification.psp.transactionId
+ notification.psp.tokenId
+ notification.psp.pspCardFingerprint
+ notification.psp.status
+ notification.customerId
+ notification.networkToken.token
+ notification.networkToken.status
+ notification.networkToken.issuer
+ notification.networkToken.originalMessage
+ notification.networkToken.isCardArtUpdated
+ "your notification shared secret";

// Convert the concatenated fields into bytes then hash the bytes using SHA-256.
const bytes = CryptoJS.enc.Utf8.parse(fields)
const hashBytes = CryptoJS.SHA256(bytes)

// Encode the resulting hash in Base64
const hashString = CryptoJS.enc.Base64.stringify(hashBytes);

// Compare the resulting hash to the hashCode in the original notification payload ensuring they match

💡

In the above example JavaScript cryptographic functions are provided by the CryptoJS library.
However the hashCode can be generated in any language that has access to cryptographic functions.

An example of the payment notification hashCode generation can be found at the following JSFiddle link

Support

If you require additional support validating notification hashes please contact support. Providing a snippet of your hash generation code, generated hash, and the original notification payload.

Updated 3 days ago