Sign product links with HMAC

How signing works

For each parameter, concatenate three values in this order:

1. 1

   The product code

2. 2

   The parameter name

3. 3

   The parameter value

Then HMAC SHA-256 that string using your store’s API key, and append the resulting 64-character hash to the parameter name using double pipes (||).

For example, a product with code of abc123 and name of My Widget priced at 1.99:

hash_hmac('sha256', 'abc123nameMy Widget', $api_key);
hash_hmac('sha256', 'abc123codemycode', $api_key);
hash_hmac('sha256', 'abc123price1.99', $api_key);

Steps

1. 1

   For each parameter, concatenate the product code, parameter name, and parameter value into a single string.

2. 2

   Generate an HMAC SHA-256 hash of that string using your store’s API key.

3. 3

   Append || and the hash to the parameter name in the URL.

4. 4

   Repeat for every parameter on every add-to-cart link.

PHP helper function

If you are using PHP, you can use this helper function to generate signed parameter names:

function get_verification($var_name, $var_value, $var_code, $var_parent_code = "", $for_value = false) {
    $api_key = "your_api_key_here";
    $encodingval = htmlspecialchars($var_code . $var_parent_code . $var_name . $var_value);
    $label = ($for_value) ? $var_value : $var_name;
    return $label . '||' . hash_hmac('sha256', $encodingval, $api_key) . ($var_value === "--OPEN--" ? "||open" : "");
}

To build a signed link using the helper:

$atc  = "?";
$atc .= get_verification("name", "My Widget", "mycode") . "=" . urlencode("My Widget");
$atc .= "&" . get_verification("code", "mycode", "mycode") . "=" . urlencode("mycode");
$atc .= "&" . get_verification("price", "1.99", "mycode") . "=" . urlencode("1.99");

Spaces and special characters

When a parameter value contains spaces or special characters, pass the raw string to the hashing function but URL-encode the value in the link itself. In PHP, use urlencode() for this. For example, "Black & White T-shirt" is passed as-is to get_verification(), but written as Black+%26+White+T-shirt in the URL.

Notes

• Every parameter that relates to a product must be signed. An unsigned parameter with a price modifier could be used to manipulate the price.

• For open (user-editable) fields, see Sign open fields with HMAC.

• For bundled products, see Sign bundled products with HMAC.

• For multiple products in one link, see Sign multiple products in one form with HMAC.

• For parameters that do not need to be signed, see HMAC excluded parameters reference.

• Forms with many signed parameters may push Internet Explorer (up to IE8) past its 2,083-character URL limit for GET submissions. POST submissions are unaffected.