HMAC Signature Verification

The section describes how the hmac signature sent in the callback header OR in the redirect data can be verified

Obtain the Signing Key

The signing key is an alpha-numeric string generated by our platform during your merchant account creation and it is stored against your account record. This value can be found under you account details in the merchant dashboard. GovBill uses this value to create the hmac signature and the same will be used when verifying the signature. It is recommended that it is copied and stored safely together with the security keys.

Below is the sample callback data to be used for the demonstration (sample redirect data is available here);

{
  "id": 268,
  "merchant_reference": "CSTREFRCPKQNDSDSYMR9",
  "internal_reference": "GOVNETKVGBF8NSJBWVZX93",
  "transaction_type": "COLLECTION",
  "request_currency": "UGX",
  "request_amount": 4500,
  "transaction_currency": "UGX",
  "transaction_amount": 4500,
  "transaction_fee": 113,
  "charge_customer": false,
  "total_credit": 4387,
  "provider_code": "mtn_momo_ug",
  "transaction_status": "FAILED",
  "status_message": "Insufficient balance on the customer account"
}

Next Steps

1. Obtain the value of the hmac-signature header (if callback) OR the value of the hmac_signature query parameter (if redirect);

2. Form the string payload to be used in signature verification. This is obtained by concatenating values of the callback/redirect data in the format; id:internal_reference:transaction_status:merchant_reference and these values are obtained from the callback/redirect data. The string payload in this case would therefore be 268:GOVNETKVGBF8NSJBWVZX93:FAILED:CSTREFRCPKQNDSDSYMR9

3. Create the hmac hash of the string payload.

4. Compare the resulting hash to the value in the hmac-signature header. Equality means the signature is valid.

PHP

<?php

public function isValidSignature() {
    $signingKey = "your signing key string";
    $strPayload = "268:GOVNETKVGBF8NSJBWVZX93:FAILED:CSTREFRCPKQNDSDSYMR9";
    $hmacSignature = "value of hmac-signature header";
    
    $signature = hash_hmac('sha256', $strPayload, $signingKey, false);

    /*true or false*/
    return $signature == $hmacSignature;
}

?>

NodeJS