HMAC Signature Authentication

To ensure data integrity and prevent tampering, every request with a body must include not only your API key but also an HMAC signature.

1. X-HMAC Header

  • Header Name: X-HMAC
  • Algorithm: HMAC-SHA256
  • Data Source: raw request body (JSON without extra spaces or formatting)
  • Secret Key: your secret key (e.g. sk_live_abcdef1234567890)
  • Signature Format: hex string, e.g. 3f8f...a1b2

2. Generating the Signature

  1. Serialize your payload to a JSON string without changing field order.
  2. Compute the HMAC-SHA256 digest of that string using your secret key.
  3. Hex-encode the resulting hash.
BODY='{"amount":"250.00","asset":{"short":"USDT","network":"tron"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "sk_live_abcdef1234567890" | cut -d" " -f2)
echo $SIGNATURE

JS:

import crypto from 'crypto';

function makeSignature(body, secret) {
return crypto
.createHmac('sha256', secret)
.update(body, 'utf8')
.digest('hex');
}

const body = JSON.stringify({
amount: '250.00',
asset: { short: 'USDT', network: 'tron' },
});
const signature = makeSignature(body, 'sk_live_abcdef1234567890');
console.log(signature);

Python:

import hmac, hashlib

body = '{"amount":"250.00","asset":{"short":"USDT","network":"tron"}}'
secret = b'sk_live_abcdef1234567890'
sig = hmac.new(secret, body.encode('utf-8'), hashlib.sha256).hexdigest()
print(sig)

3. Full cURL Request

curl https://api.alppay.io/v2/payment \
-X POST \
-H "Content-Type: application/json" \
-H "API-KEY: ak_live_1234567890abcdef" \
-H "X-HMAC: 3f8fa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0" \
-d '{"amount":"250.00","asset":{"short":"USDT","network":"tron"}}'

4. Potential Errors

  • 400 Bad Request: malformed JSON or incorrect field order.
  • 401 Unauthorized: missing or invalid signature.
  • 422 Unprocessable Entity: payload is valid JSON but failed business validation.
  • Debugging Tip: log both BODY and SIGNATURE, then compare on the server.

Important: Always generate a fresh signature for each unique payload and store your secret key securely (Vault, KMS).