Request Signing

All requests and responses are secured using an HMAC SHA256 signature.

The signature ensures:

• data integrity (the request/response has not been altered)
• authenticity (the sender is verified)

---

Hash Generation

The hash is generated by:

• selecting specific fields (defined per API endpoint)
• concatenating their values in the exact order defined for that endpoint
• without separators
• applying the HMAC SHA256 algorithm using the Merchant's secret key
• encoding the result as a lowercase hexadecimal string

The secret key is provided by HPGames during integration setup.

---

Field Order

The exact fields and their order are defined individually for each endpoint.

Each API method specifies:

• which fields are included in the hash
• the exact order in which they must be concatenated

Fields not explicitly listed must be ignored.

The hash field itself must never be included in the calculation.

---

Encoding Rules

• All values must be encoded using UTF-8
• Field values must be converted to their string representation before concatenation
• Fields must be concatenated exactly as sent (no trimming or modification)

---

Numeric Values

Numeric values (e.g. amount) must be formatted exactly as they appear in the request when generating the hash.

For example:

• 1
• 1.0
• 1.00

These values produce different hashes.

---

Example (Java)

The following example demonstrates how to generate an HMAC SHA256 hash.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class HmacSha256Example {
    public static void main(String[] args) throws Exception {
        String merchantId = "1387a6cc-3651-4473-ae52-e415caea3395";
        String timestamp = "1709289932725";

        String message = merchantId + timestamp;
        String secretKey = "apikey";

        String hash = calculateHmacSha256(message, secretKey);
        System.out.println(hash);
    }

    private static String calculateHmacSha256(String message, String secretKey) throws Exception {
        String algorithm = "HmacSHA256";

        SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), algorithm);
        Mac mac = Mac.getInstance(algorithm);
        mac.init(keySpec);

        byte[] hmacBytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));

        return bytesToHex(hmacBytes);
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder hex = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            String s = Integer.toHexString(0xff & b);
            if (s.length() == 1) hex.append('0');
            hex.append(s);
        }
        return hex.toString();
    }
}