Integrating QZPAY API

Python:

Python
import hashlib, hmac, json

def sign(method, path, body, ts, key):
    body_str = json.dumps(body, sort_keys=True) if body else ''
    body_hash = hashlib.sha256(body_str.encode()).hexdigest()
    sts = f"{method}:{path}:{body_hash}:{ts}"
    return hmac.new(key.encode(), sts.encode(), hashlib.sha256).hexdigest()

PHP:

PHP
function sign($method, $path, $body, $ts, $key) {
  $bodyStr = $body ? json_encode($body) : '';
  $bodyHash = strtolower(hash('sha256', $bodyStr));
  $sts = "$method:$path:$bodyHash:$ts";
  return hash_hmac('sha256', $sts, $key);
}

Go:

Go
func sign(method, path string, body any, ts, key string) string {
  var b []byte
  if body != nil { b, _ = json.Marshal(body) }
  h := sha256.Sum256(b)
  sts := method + ":" + path + ":" + hex.EncodeToString(h[:]) + ":" + ts
  mac := hmac.New(sha256.New, []byte(key))
  mac.Write([]byte(sts))
  return hex.EncodeToString(mac.Sum(nil))
}

Bash (for scripts/testing):

Bash
BODY_HASH=$(echo -n "$BODY" | sha256sum | cut -d" " -f1)
STRING_TO_SIGN="POST:/v2/payments:${BODY_HASH}:${TIMESTAMP}"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$API_KEY" | awk '{print $NF}')

Always use constant-time comparison to prevent timing attacks.

JavaScript
function verifyWebhook(payload, signature, secret) {
  const expected = crypto.createHmac('sha256', secret)
    .update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Python
def verify_webhook(payload: dict, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), json.dumps(payload, separators=(',', ':')).encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Handle idempotently: dedupe on data.id or data.referenceId since the same event may be delivered multiple times (retries at 0s, 10s, 30s, 60s, 5min if you don't return HTTP 200 within 5s).

• Sort JSON keys deterministically before hashing the body — mismatched key order between client/server causes signature failures.
• Always send Idempotency-Key (UUID) on POST requests to avoid double-charging on retries.
• Request only the scopes needed per key (payment:create, balance:read, etc.) — principle of least privilege.
• Use webhooks instead of polling; reserve GET status checks for reconciliation/fallback only.
• On HTTP 429, apply exponential backoff — don't hammer retries.
• Respond to webhooks with HTTP 200 immediately; do heavy processing asynchronously.
• Log webhook events for debugging, but never log the signature or API key value.

• Never put the API Key in frontend/client-side JS or commit it to GitHub — it's shown only once at creation.
• Don't use ===/== for webhook signature comparison — use timingSafeEqual/compare_digest to avoid timing attacks.
• Don't forget the empty-body SHA256 hash constant for GET/DELETE requests — signing with an empty string literal instead breaks verification.
• Don't assume timestamp is lenient — window is ±5 minutes UTC; clock drift causes silent 401s.
• Don't skip idempotency handling on webhook receivers — duplicate deliveries are expected, not a bug.
• Don't poll payment status in a tight loop — this burns rate limit (300 req/min default, 10 req/sec burst) and webhooks exist specifically to avoid this.