HMAC-SHA256 Authentication: XPayLabs API Security

XPayLabs authenticates every API request using HMAC-SHA256 request signing. Unlike traditional Bearer token authentication, XPayLabs requires each request to include a cryptographic signature computed over the request payload. This ensures request integrity and prevents replay attacks.

What is the HMAC-SHA256 signing format?

Every API request includes a ReqPayload wrapper with four fields:

Field	Type	Description
`sign`	string	HMAC-SHA256 signature of the stringified `data` object
`timestamp`	integer	Unix timestamp (seconds) of when the request was created
`nonce`	string	A unique random string, never reused
`data`	object	The actual request payload

The sign field is computed using your merchant token as the HMAC secret key.

How to compute the HMAC signature

Algorithm

Serialize the data object as a JSON string (no pretty-printing, no extra whitespace).
Compute HMAC-SHA256(data_json, merchant_token).
Convert the result to a lowercase hex string.
Set this value as the sign field.

Node.js

import crypto from "crypto";

const MERCHANT_TOKEN = process.env.XPAYLABS_MERCHANT_TOKEN;

function signRequest(data) {
  const json = JSON.stringify(data);   // compact JSON, no extra whitespace
  return crypto
    .createHmac("sha256", MERCHANT_TOKEN)
    .update(json, "utf8")
    .digest("hex");
}

const request = {
  sign: signRequest({ amount: "100.00", symbol: "USDT", chain: "TRON" }),
  timestamp: Math.floor(Date.now() / 1000),
  nonce: crypto.randomUUID(),
  data: { amount: "100.00", symbol: "USDT", chain: "TRON" },
};

Python

import hmac
import hashlib
import json
import time
import uuid

MERCHANT_TOKEN = "your-merchant-token"

def sign_request(data: dict) -> str:
    json_str = json.dumps(data, separators=(",", ":"))  # compact JSON
    return hmac.new(
        MERCHANT_TOKEN.encode("utf-8"),
        json_str.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

request = {
    "sign": sign_request({"amount": "100.00", "symbol": "USDT", "chain": "TRON"}),
    "timestamp": int(time.time()),
    "nonce": str(uuid.uuid4()),
    "data": {"amount": "100.00", "symbol": "USDT", "chain": "TRON"},
}

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "time"
    "github.com/google/uuid"
)

func signRequest(data interface{}, token string) string {
    jsonBytes, _ := json.Marshal(data)
    mac := hmac.New(sha256.New, []byte(token))
    mac.Write(jsonBytes)
    return hex.EncodeToString(mac.Sum(nil))
}

func main() {
    data := map[string]interface{}{
        "amount":  "100.00",
        "symbol":  "USDT",
        "chain":   "TRON",
    }
    request := map[string]interface{}{
        "sign":      signRequest(data, "your-merchant-token"),
        "timestamp": time.Now().Unix(),
        "nonce":     uuid.New().String(),
        "data":      data,
    }
    fmt.Printf("%+v\n", request)
}

The JSON serialization must be compact — no spaces, no newlines between key-value pairs. Different JSON serializers may produce different output; always test your signature computation against a known working example.

What are the timestamp and nonce requirements?

The timestamp and nonce fields prevent replay attacks:

Timestamp: Your server clock must be within 5 minutes of XPayLabs server time. Requests with timestamps older than 5 minutes are rejected.
Nonce: Each request must use a unique nonce. XPayLabs tracks used nonces and rejects duplicates. UUIDs or cryptographically random strings work well.

How does XPayLabs verify signatures server-side?

XPayLabs verifies every request by recomputing the HMAC-SHA256 signature using your stored merchant token. If the signatures don’t match, or if the timestamp is outside the tolerance window, the request is rejected with a 401 Unauthorized response.

How to keep your merchant token secure

Store your merchant token in an environment variable or secrets manager.
Never hardcode the token in source code or client-side applications.
Rotate the token periodically and update your configuration.
The token is a shared secret between your merchant server and the XPayLabs gateway. It is not sent over the network in API requests.

​What is the HMAC-SHA256 signing format?

​How to compute the HMAC signature

​Algorithm

​Node.js

​Python

​Go

​What are the timestamp and nonce requirements?

​How does XPayLabs verify signatures server-side?

​How to keep your merchant token secure

What is the HMAC-SHA256 signing format?

How to compute the HMAC signature

Algorithm

Node.js

Python

Go

What are the timestamp and nonce requirements?

How does XPayLabs verify signatures server-side?

How to keep your merchant token secure