The payloads checksum ensures data integrity and consistency during API requests.

On incoming requests it ensures that the payment or payout request is from a valid merchant and that no one has tampered with it.

Webhooks payload are also signed using the same method as defined below. This allows merchants to ensure that the webhook request came from ClickPesa and that no one has tampered with it.

​
Generating Payload Checksum

  1. Sort Payload Keys - The keys of the payload are sorted alphabetically to maintain consistency.
  2. Concatenate Sorted Values - The values of the sorted object are concatenated into a single string.
  3. Generate HMAC-SHA256 Hash - The concatenated string is hashed using HMAC-SHA256 with the provided secret key.
  4. Return the Hex Digest - The resulting hash is returned in hexadecimal format.
  • The order of values matters, so sorting is crucial to maintain consistency.
  • The function assumes all values are strings; if they contain complex types, they should be serialized properly before hashing.

​
Examples

const crypto = require("crypto");

const createPayloadChecksum = (checksumKey, payload) => {
  const sortedPayload = Object.keys(payload)
    .sort()
    .reduce((obj, key) => {
      obj[key] = payload[key];
      return obj;
    }, {});
  const payloadString = Object.values(sortedPayload).join("");
  const hmac = crypto.createHmac("sha256", checksumKey);
  hmac.update(payloadString);
  return hmac.digest("hex");
};

// Example usage:
const payload = { amount: 100, currency: "USD", reference: "TX123" };
const checksumKey = "secret-key";
console.log(createPayloadChecksum(checksumKey, payload));

​
Validating Payload Checksum

  1. Extract Checksum - Extract the checksum from the received request.

  2. Recompute Checksum - Using the same createPayloadChecksum function, recompute the checksum from the received payload using the checksum key.

  3. Compare the Computed and Received Checksum

    • If both checksums match, the payload is valid and untampered.
    • If they do not match, reject the request as it may have been modified.

​
Examples

const crypto = require("crypto");

const createPayloadChecksum = (checksumKey, payload) => {
  const sortedPayload = Object.keys(payload)
    .sort()
    .reduce((obj, key) => {
      obj[key] = payload[key];
      return obj;
    }, {});
  const payloadString = Object.values(sortedPayload).join("");
  const hmac = crypto.createHmac("sha256", checksumKey);
  hmac.update(payloadString);
  return hmac.digest("hex");
};

const validateChecksum = (checksumKey, payload, receivedChecksum) => {
  const computedChecksum = createPayloadChecksum(checksumKey, payload);
  return computedChecksum === receivedChecksum;
};

// Example usage:
const payload = { amount: 100, currency: "USD", reference: "TX123" };
const checksumKey = "secret-key";
const receivedChecksum = "some-checksum-from-request"; // Replace with actual received checksum

console.log(validateChecksum(checksumKey, payload, receivedChecksum) ? "Valid" : "Invalid");