Getting Started

Welcome to the CryptoGate Merchant API Reference. CryptoGate enables online stores, SaaS platforms, and digital businesses to easily accept 10+ major cryptocurrencies across 8 leading blockchains with zero processing fees.

The gateway operates fully serverless on Vercel and uses MongoDB to store invoices, transactions, and webhook logs. Integrating the gateway requires only a few lines of code.

Authentication

To authenticate API requests, you must pass your merchant API key in the headers of each request. You can locate your API Key and Secret inside your merchant settings dashboard.

{
  "X-API-Key": "your_merchant_api_key"
}

Create Payment

Generates a new on-chain invoice with a unique wallet address derived via HD Wallet (BIP44) and returns a visual QR Code for checkout.

You can define the amount directly in cryptocurrency or in fiat USD (fiat amount is auto-calculated using the live Binance Public API).

POST /api/v1/payments

Request Parameters

Parameter Type Required Description
currency string Yes Payment asset symbol (e.g. USDT_TRC20, BTC, ETH, SOL, USDC_POLYGON)
amount number No Asset token value. Required if fiatAmount is omitted.
fiatAmount number No USD value. Payment calculates matching crypto units based on live Binance conversion.
fiatCurrency string No Required if fiatAmount is set. Value: USD.
orderId string No Merchant reference id (max 100 chars).
callbackUrl string No Webhook URL target for payment notifications.

Sample Implementation

curl -X POST https://yourgateway.vercel.app/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "fiatAmount": 100.0,
    "fiatCurrency": "USD",
    "currency": "USDT_TRC20",
    "orderId": "order_77491",
    "callbackUrl": "https://yoursite.com/webhooks"
  }'

Get Payment Details

Query the current confirmation status, expire timer, amounts, and on-chain addresses for any created payment ID.

GET /api/v1/payments/:id 
{
  "success": true,
  "data": {
    "id": "pay_9a2f1c8b...",
    "amount": 100,
    "currency": "USDT_TRC20",
    "status": "COMPLETED",
    "walletAddress": "TXZ198sY...",
    "fiatAmount": 100,
    "fiatCurrency": "USD",
    "exchangeRate": 1.0,
    "paidAmount": 100,
    "paidAt": "2026-07-05T12:00:00.000Z",
    "expiresAt": "2026-07-05T12:30:00.000Z"
  }
}

Webhook Notifications

When a transaction changes status (detected, confirming, completed, or expired), CryptoGate dispatches an HTTP POST payload to the configured merchant callbackUrl.

The webhook payload includes the transaction hash and a verification signature. If delivery fails (recipient server offline or 500 error), the system logs it and schedules retries automatically with exponential backoff (1 min, 5 min, 15 min, 60 min, 240 min).

{
  "event": "payment.updated",
  "paymentId": "pay_d7b88e1a...",
  "timestamp": 1783339200000,
  "data": {
    "orderId": "order_77491",
    "status": "COMPLETED",
    "amount": 100.00,
    "currency": "USDT_TRC20",
    "txHash": "a67b2fc91..."
  }
}

Verifying Webhook Signatures

To confirm webhooks were legitimately dispatched by your CryptoGate instance and not intercepted/forged, verify the X-Webhook-Signature request header using your merchant API Secret.

const crypto = require('crypto');

function verifySignature(reqBody, headerSignature, apiSecret) {
  const payload = JSON.stringify(reqBody);
  const expectedSignature = crypto
    .createHmac('sha256', apiSecret)
    .update(payload)
    .digest('hex');

  return `sha256=${expectedSignature}` === headerSignature;
}