HMAC Signature Verification

This section describes how the hmac signature sent in the callback header 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. Qwaap 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;

COLLECTION

{
    "id": 2061,
    "request_amount": 10000,
    "request_currency": "UGX",
    "transaction_fee": 1000,
    "total_credit": 9000,
    "invoice_number": "QINVNHNU4FMGMHBKA8YQ",
    "merchant_reference": "1184",
    "payment_status": "PAID",
    "transaction_type": "COLLECTION",
    "status_message": "Invoice payment successful"
}

Payout

{
  "id": 2839,
  "merchant_reference": "5547",
  "internal_reference": "QWAAPDQNSRPEJXXUDGVXN",
  "transaction_type": "PAYOUT",
  "request_currency": "UGX",
  "request_amount": 13000,
  "transaction_currency": "UGX",
  "transaction_amount": 13000,
  "transaction_fee": 1000,
  "total_debit": 15000,
  "charge_customer": "N",
  "provider_code": "mtn_ug",
  "transaction_status": "FAILED",
  "status_message": "256777000456 is not registered for mobile money"
}

Next Steps

1. Obtain the value of the hmac-signature header;

2. Form the string payload to be used in signature verification. This is obtained by concatenating values of the callback data in the format; For Collections:

   strPayload = `${payload.id}:${payload.invoice_number}:${payload.payment_status}:${payload.merchant_reference}`;

   id:invoice_number:payment_status:merchant_reference and these values are obtained from the callback data. The string payload in this case would therefore be 2061:QINVNHNU4FMGMHBKA8YQ:PAID:1184 For Payouts: id:internal_reference:transaction_status:merchant_reference and these values are obtained from the callback data. The string payload in this case would therefore be 2839:QWAAPDQNSRPEJXXUDGVXN:FAILED:5547

   strPayload = `${payload.id}:${payload.internal_reference}:${payload.transaction_status}:${payload.merchant_reference}`;

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 = "2061:QINVNHNU4FMGMHBKA8YQ:PAID:1184";
    $hmacSignature = "value of hmac-signature header";
    
    $signature = hash_hmac('sha512', $strPayload, $signingKey, false);

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

?>

NodeJS

/* For payouts, replace strPayload with the payout strPayload as described in step 2*/
const crypto = require('crypto');

function isValidSignature() {
    const strPayload = "2061:QINVNHNU4FMGMHBKA8YQ:PAID:1184";
    const hmacSignature = "value of hmac-signature header";
    const signingKey = "your signing key string";

    const signature = crypto.createHmac("sha512", signingKey).update(strPayload).digest("hex");

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

A valid hmac signature for the above sample callback is shared below. You can copy and use it to test your signature verification workflow.

dd8b832121416dbb2b75897e8026c52b8327ba3e260716c341fe82bb0e02cc6537d644e7cb161b09d43a433ab06ffdf92aa162bfcbba9283ce2d3a766388cdbd