HMAC Signature

info

By validating the HMAC signature, your system can verify that messages are genuinely from the Straumur and have not been altered in transit.

Here’s how each component of the HMAC validation process works:

• Secret Key: A shared, secure key known only to the Straumur and your system. This key is used to generate the HMAC signature, allowing both parties to verify message authenticity.
• Payload: The message body of the webhook, which includes merchant related details. The payload is hashed along with the secret key to generate the HMAC signature.
• HMAC Signature: A cryptographic hash produced by the Straumur, using the payload and the secret key. Your system should generate its own HMAC using the received payload and compare it with the HMAC signature provided in the webhook.

Merchant management HMAC

Merchant management HMAC signature calculation is dependant on the order and the values of the payload properties.

When generating the merchant management signature, Straumur uses this order: PartnerContractNumber, MerchantNumber, ContractNumber, Mid, Tid, TerminalIdentifier.

Example Signature

Use the following payload and the secret key: 42355b343e1a8879b54906abe30e25c0f4f2e1b7d29ad9f1

{
    "partnerContractNumber": "73538280",
    "ssn": "1111111119",
    "merchantNumber": "7366746",
    "contractNumber": "32305",
    "mid": "2913122972",
    "tid": "3fdd19ef",
    "terminalIdentifier": "3703ed39e197",
    "hmacSignature": "G8MRsh6OAZf+anQ+0VWcp3PNRNVBqxmpW3mOimqmbdM=",
    "additionalData": {
        "eventType": "TerminalAdded",
        "eventTime": "2025-09-19T10:14:46.6730082Z",
    }
}

The resulting HMAC signature should be:

G8MRsh6OAZf+anQ+0VWcp3PNRNVBqxmpW3mOimqmbdM=

HMAC Calculator

hmacKey

PartnerContractNumber

Ssn

MerchantNumber

ContractNumber

Mid

Tid

TerminalIdentifier

HMAC Signature

Calculating...

C#

using System;
using System.Security.Cryptography;
using System.Text;
using System.Linq;

var message = new WebhookMessage {
    PartnerContractNumber="73538280"
    Ssn="1111111119"
    MerchantNumber="7366746"
    ContractNumber="32305"
    Mid="2913122972"
    Tid="3fdd19ef"
    TerminalIdentifier="3703ed39e197"
    HmacSignature = string.Empty, // We calculate the signature below.
};

var hmacKey = "42355b343e1a8879b54906abe30e25c0f4f2e1b7d29ad9f1";
CalculateSignature(hmacKey, message);

Console.WriteLine(message.HmacSignature);
// Output: G8MRsh6OAZf+anQ+0VWcp3PNRNVBqxmpW3mOimqmbdM=

static void CalculateSignature(string hmacKey, WebhookMessage message)
{
    message.HmacSignature = GetHmacSignature(
    hmacKey,
    message.PartnerContractNumber,
    message.Ssn,
    message.MerchantNumber,
    message.ContractNumber,
    message.Mid,
    message.Tid,
    message.TerminalIdentifier);
}

static string GetHmacSignature(string hmacKey, params string?[] values)
{
    var payload = string.Join(':', values.Select(x => x ?? string.Empty));
    var binaryPayload = ConvertToByteArray(payload, Encoding.UTF8);
    var binaryKey = ConvertHexToByteArray(hmacKey);
    var hash = ComputeSha256Hash(binaryPayload, binaryKey);
    return Convert.ToBase64String(hash);
}

static byte[] ConvertToByteArray(string str, Encoding encoding)
{
    return encoding.GetBytes(str);
}

static byte[] ConvertHexToByteArray(string hex)
{
    if ((hex.Length % 2) == 1)
    {
        hex += '0';
    }

    var bytes = new byte[hex.Length / 2];
    for (var i = 0; i < hex.Length; i += 2)
    {
    	bytes[i / 2] = Convert.ToByte(hex.Substring(i, 2), 16);
    }

    return bytes;
}

static byte[] ComputeSha256Hash(byte[] payload, byte[] key)
{
    using HMACSHA256 hmacSha256Hash = new(key);
    return hmacSha256Hash.ComputeHash(payload);
}

public class WebhookMessage
{
    public required string PartnerContractNumber { get; set; }

    public required string Ssn { get; set; }

    public required string MerchantNumber { get; set; }
    
    public required string ContractNumber { get; set; }
    
    public required string Mid { get; set; }
    
    public required string Tid { get; set; }
    
    public required string? TerminalIdentifier { get; set; }
    
    public string HmacSignature { get; set; } = null!;

    public WebhookAdditionalData? AdditionalData { get; set; }
}

public class WebhookAdditionalData
{
    public required string EventType { get; set; }

    public required string EventTime { get; set; }
}

JavaScript

import crypto from "crypto";

class WebhookMessage {
    constructor({
        PartnerContractNumber,
        Ssn,
        MerchantNumber,
        ContractNumber,
        Mid,
        Tid,
        TerminalIdentifier = "",
        HmacSignature = "",
        AdditionalData = null,
    }) {
        this.PartnerContractNumber = PartnerContractNumber;
        this.Ssn = Ssn;
        this.MerchantNumber = MerchantNumber;
        this.ContractNumber = ContractNumber;
        this.Mid = Mid;
        this.Tid = Tid;
        this.TerminalIdentifier;
        this.HmacSignature = HmacSignature;
        this.AdditionalData = AdditionalData;
    }
}

class WebhookAdditionalData {
    constructor({ EventType = null, EventTime = null } = {}) {
        this.EventType = EventType;
        this.EventTime = EventTime;
    }
}

function convertHexToByteArray(hex) {
    if (hex.length % 2 === 1) {
        hex += "0";
    }
    return Buffer.from(hex, "hex");
}

function computeSha256Hash(payload, key) {
    return crypto.createHmac("sha256", key).update(payload).digest();
}

function getHmacSignature(hmacKey, ...values) {
    const payload = values.map(v => v ?? "").join(":");
    const binaryPayload = Buffer.from(payload, "utf8");
    const binaryKey = convertHexToByteArray(hmacKey);
    const hash = computeSha256Hash(binaryPayload, binaryKey);
    return hash.toString("base64");
}

function calculateSignature(hmacKey, message) {
    message.HmacSignature = getHmacSignature(
        hmacKey,
        message.PartnerContractNumber,
        message.Ssn,
        message.MerchantNumber,
        message.ContractNumber,
        message.Mid,
        message.Tid,
        message.TerminalIdentifier
    );
}

const message = new WebhookMessage({
    PartnerContractNumber: "73538280",
    Ssn: "7366746",
    MerchantNumber: "7366746",
    ContractNumber: "32305",
    Mid: "2913122972",
    Tid: "3fdd19ef",
    TerminalIdentifier: "3703ed39e197",
    HmacSignature: "", // We calculate the signature below.
});

const hmacKey = "42355b343e1a8879b54906abe30e25c0f4f2e1b7d29ad9f1";

calculateSignature(hmacKey, message);

console.log(message.HmacSignature);
// Expected output: G8MRsh6OAZf+anQ+0VWcp3PNRNVBqxmpW3mOimqmbdM=