API Documentation (Crypto) (v2)

You are helping me integrate the Matrix Pay Crypto (USDT) payment gateway API into my application. Use only the specification below. Do not guess at endpoints, field names, or behaviour that is not written here, and do not try to fetch the documentation online: it sits behind an authenticated merchant dashboard and is not publicly reachable.

# 1. Non-negotiable constraints

1. This is a SERVER-TO-SERVER API. It enforces strict request validation and rejects browser-origin requests with CORS errors. Never call it from frontend JavaScript, browser applications, or mobile client code. All API calls must originate from my backend server.
2. The base host is https://matrixpay.vercel.app. THIS IS THE LIVE PRODUCTION HOST. There is no sandbox environment and no mock test mode. Testing is performed directly against production using real low-cost transactions of $1 USDT. Every transaction interacts with real on-chain deposit addresses.
3. Every API call is an HTTP POST request with a JSON body and Content-Type: application/json.
4. Authentication is performed via canonical HMAC-SHA256 request signing sent in custom HTTP request headers. Never put the API Secret Key in the JSON request body or URL parameters.
   Required headers on every request:
   - X-Client-Id: My Merchant Live Client ID
   - X-Signature: Hex-encoded HMAC-SHA256 signature
   - X-Timestamp: Unix timestamp in seconds (integer string, valid within ±300s window)
   - X-Nonce: Cryptographically random unique nonce string (8-16 bytes hex, replay protection)
5. HMAC-SHA256 Request Signing Protocol:
   - Canonicalize the JSON body: sort all keys alphabetically (A-Z) recursively, eliminate all whitespace between keys and values.
   - Construct signing string: "${canonical_json_body}.${timestamp}.${nonce}"
   - Compute HMAC-SHA256 using my API Secret Key as the HMAC key. Output the result as a lowercase hexadecimal string.
6. Supported Chains: TRC20 (Tron), BEP20 (Binance Smart Chain), ERC20 (Ethereum), POLYGON (Matic), SOLANA, ARBITRUM, OPTIMISM. Supported token: USDT.
7. IP Whitelisting: My server's static outbound IP address must be registered in the Developer Hub -> IP Whitelist tab. Requests originating from unlisted IPs are rejected with 403 IP_RESTRICTED.
8. The API Secret Key is confidential. It must never appear in frontend code, version control commits, public repositories, or client-side network inspect tabs. Store it as a secure environment variable on the server.

# 2. Endpoints

All endpoints accept HTTP POST with JSON body and the 4 authentication headers.

## Create Crypto (USDT) Order
POST https://matrixpay.vercel.app/api/v2/payment_gateway/create_crypto_order
Headers:
  Content-Type: application/json
  X-Client-Id: <client_id>
  X-Signature: <hmac_sha256_signature>
  X-Timestamp: <timestamp_seconds>
  X-Nonce: <unique_nonce>
Request Body:
{
  "customer_name": "Customer Name",
  "customer_email": "customer@example.com",
  "customer_mobile": "9876543210",
  "amount": 10.00,
  "token": "USDT",
  "chain": "TRC20",
  "customer_reference": "YOUR_UNIQUE_CRYPTO_REF",
  "redirect_url": "https://yourstore.com/checkout/return",
  "service_type": "CRYPTO"
}
Response (HTTP 200 or 201):
{
  "order_id": "MP_CRYPTO_7JEV_9011",
  "customer_reference": "YOUR_UNIQUE_CRYPTO_REF",
  "amount": 10.00,
  "token": "USDT",
  "chain": "TRC20",
  "deposit_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "payment_url": "https://matrixpay.vercel.app/pay/MP_CRYPTO_7JEV_9011",
  "status": "pending",
  "required_confirmations": 3,
  "expires_at": "2026-09-24T12:00:00Z"
}

## Check Crypto Order Status
POST https://matrixpay.vercel.app/api/v2/payment_gateway/check_crypto_order_status
Headers:
  Content-Type: application/json
  X-Client-Id: <client_id>
  X-Signature: <hmac_sha256_signature>
  X-Timestamp: <timestamp_seconds>
  X-Nonce: <unique_nonce>
Request Body:
{
  "order_id": "MP_CRYPTO_7JEV_9011"
}
Response (HTTP 200 or 422):
{
  "order_id": "MP_CRYPTO_7JEV_9011",
  "customer_reference": "YOUR_UNIQUE_CRYPTO_REF",
  "amount": 10.00,
  "token": "USDT",
  "chain": "TRC20",
  "status": "success",
  "tx_hash": "0x5b3a4a1c6e1f0e2b9c7d4a3e2f1b0a9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a",
  "confirmations": 12,
  "paid_at": "2026-09-24T10:15:30Z"
}

# 3. Order Lifecycle & Statuses

The workflow sequence is:
  1. Generate unique customer_reference on your server (e.g. CRYPTO_${Date.now()}_${randomUUID()}).
  2. Call create_crypto_order with canonical HMAC-SHA256 signature headers.
  3. Store order_id, deposit_address, and reference in your database.
  4. Display deposit_address and QR code or redirect user to payment_url.
  5. Listen for incoming webhook notifications OR poll check_crypto_order_status until confirmed on-chain.

There are exactly four order statuses:
  pending    Deposit address assigned, awaiting on-chain transaction or confirmations. Not terminal.
  success    On-chain transaction verified and confirmations reached. Terminal. Grant credit or fulfil goods.
  refunded   Transaction refunded or returned. Terminal.
  failed     Order window expired without deposit. Terminal.

# 4. Webhook Handling

Matrix Pay delivers asynchronous HTTP POST event updates to your configured Webhook URL when on-chain confirmations complete.
Incoming Webhook Headers:
  Content-Type: application/json
  X-Webhook-Signature: <hmac_sha256_hex_signature>
  X-Webhook-Event: payment.success | payment.failed | payment.refunded
  X-Webhook-Id: <delivery_uuid>
Webhook Payload:
{
  "event": "payment.success",
  "order_id": "MP_CRYPTO_7JEV_9011",
  "customer_reference": "YOUR_UNIQUE_CRYPTO_REF",
  "amount": 10.00,
  "token": "USDT",
  "chain": "TRC20",
  "status": "success",
  "tx_hash": "0x5b3a4a1c6e1f0e2b9c7d4a3e2f1b0a9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a",
  "confirmations": 12,
  "timestamp": 1735689600
}

Signature Verification:
  You MUST verify the signature using the raw request body buffer/string before JSON parsing:
  expected_sig = HMAC_SHA256(secret = API_KEY, message = raw_request_body_string)
  Compare expected_sig with header "X-Webhook-Signature" using a constant-time comparison.
  Reject with 401 Unauthorized if signatures do not match. Respond with 200 OK immediately once verified.

# 5. How I want the integration written

- Implement a single, clean backend client class or module (e.g. MatrixPayCryptoClient).
- Keep API credentials strictly in environment variables (MATRIXPAY_CLIENT_ID and MATRIXPAY_API_KEY).
- Persist the customer_reference before sending the request and treat it as the idempotency key.
- Never retry a creation request with a new reference on network timeout — look up the order with check_crypto_order_status instead.
- Implement exponential backoff retry logic for transient errors (HTTP 500, 502, 503).
- Do not retry client errors (HTTP 400, 401, 403, 429).
- Never log raw API secrets or sensitive signing keys.

# 6. What I want from you

Ask me which backend language/framework I am using (e.g. Node.js/TypeScript, Python/FastAPI/Django, PHP/Laravel, Go, Java/Spring, C#/.NET) and whether I prefer webhook delivery or status polling, then write the complete, production-ready integration client and webhook handler.