HMAC verification

All requests sent from Genstore to your app include an hmac parameter. You must validate this parameter using HMAC-SHA256 to ensure that the request is authentic and has not been tampered with.

This guide explains how to extract parameters, generate a signature, and validate the HMAC value.

Verification overview

To validate a request from Genstore, you need to:

1. Remove the hmac parameter from the query string
2. Sort the remaining parameters alphabetically and concatenate them into a string
3. Generate an HMAC-SHA256 signature using your app’s client secret
4. Compare the generated signature with the hmac value in the request
   • If they match → the request is valid
   • If not → reject the request

Step 1: Remove the hmac parameter

Example request from Genstore:

shop={shop}&shopId={shopId}&timestamp={timestamp}&hmac={hmac}

Before validation, remove the hmac parameter:

shop={shop}&shopId={shopId}&timestamp={timestamp}

Step 2: Sort and concatenate parameters

Sort all non-hmac parameters alphabetically by key, then concatenate them into a single string using the format:

shop={shop}&shopId={shopId}&timestamp={timestamp}

Important rules:

• Do not include the hmac parameter
• Do not URL-decode or encode the values
• Use = between keys and values
• Use & between parameters
• Do not add spaces or line breaks

Step 3: Generate the HMAC-SHA256 signature

Use your app’s client secret as the key and the concatenated parameter string as the message. Generate an HMAC-SHA256 signature and convert the result to a hexadecimal string.

Example (Java):

String secret  = "client_secret";
String message = "shop={shop}&shopId={shopId}&timestamp={timestamp}";

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] bytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));

Convert bytes into a hex string — this becomes your calculated signature.

Step 4: Validate the hmac value

Compare your calculated signature with the hmac value from the request:

• Match → the request is authentic
• Mismatch → the request is invalid and should be rejected

---

Common causes of validation failures

• Parameters not sorted alphabetically
• URL decoding or encoding applied incorrectly
• Incorrect client secret
• Extra whitespace or formatting changes in the message string
• Including the hmac parameter in the calculation