HMAC Signature

info

By validating the HMAC signature, your system can verify that messages are genuinely from the payment provider 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 payment provider 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 transaction details. The payload is hashed along with the secret key to generate the HMAC signature.
• HMAC Signature: A cryptographic hash produced by the payment provider, 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.

To validate the HMAC signature:

• Recreate the HMAC using the shared secret key and the webhook payload.
• Compare the generated HMAC with the HMAC signature from the webhook message.
• If they match, the message is verified; if not, reject the message to avoid processing potentially altered data.
• This process ensures secure handling of webhook data and helps prevent unauthorized access or tampering.

Calculating HMAC

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

When generating the signature, Straumur uses this order: CheckoutReference, PayfacReference, MerchantReference, Amount, Currency, Reason, Success.

Example Signature

Use the following payload and the secret key: 4eab969bd65a39c17c906dfcef1fe69d481716b0845a6c0892284cf9c06e4314

{
    "checkoutReference": null,
    "payfacReference": "21135253156",
    "merchantReference": "9990QQAZ1221",
    "amount": "48900",
    "currency": "ISK",
    "reason": null,
    "success": "true",
}

The resulting HMAC signature should be:

oH4Sgo4cZ/O8489HQU7TbcvohJkH4eHbz50Q3G+VXfk=

Example C# Demo

using System;
using System.Security.Cryptography;
using System.Text;
using System.Linq;
					
var message = new WebhookMessage
{
	CheckoutReference = null,
	PayfacReference = "21135253156",
	MerchantReference = "9990QQAZ1221",
	Amount = "48900",
	Currency = "ISK",
	Reason = null,
	Success = "true",
	HmacSignature = string.Empty, // We calculate the signature below.
};

var hmacKey = "4eab969bd65a39c17c906dfcef1fe69d481716b0845a6c0892284cf9c06e4314";
CalculateSignature(hmacKey, message);

Console.WriteLine(message.HmacSignature);
// Output: oH4Sgo4cZ/O8489HQU7TbcvohJkH4eHbz50Q3G+VXfk=
	
static void CalculateSignature(string hmacKey, WebhookMessage message)
{
	message.HmacSignature = GetHmacSignature(
		hmacKey,
		message.CheckoutReference,
		message.PayfacReference,
		message.MerchantReference,
		message.Amount,
		message.Currency,
		message.Reason,
		message.Success);
}

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? CheckoutReference {get; set; }

	public required string PayfacReference { get; set; }

	public required string? MerchantReference { get; set; }

	// Amount in minor units
	public required string Amount { get; set; }

	public required string Currency { get; set; }

	public required string? Reason { get; set; }

	public required string Success { get; set; }

	public required string HmacSignature { get; set; }

	public WebhookAdditionalData? AdditionalData { get; set; }
}

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

    public string? CardNumber { get; set; }  

    public string? CardUsage { get; set; }  

    public string? ThreeDAuthenticated { get; set; }  

    public string? OriginalPayfacReference { get; set; }  
 
    public string? PaymentMethod { get; set; }  

    public string? CardSummary { get; set; }  

    public string? AuthCode { get; set; }  

    public string? Token { get; set; }  
}