Documentation

Quick Start

Get up and running with USDT payments in three steps.

# Test mode (for development)
Authorization: Bearer test_abc123...

# Live mode (for production)
Authorization: Bearer live_xyz789...

curl -X POST https://api.example.com/api/v1/invoices \
  -H "Authorization: Bearer test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-001",
    "assetCode": "USDT_TRC20",
    "amountUsdt": 100.0000,
    "callbackUrl": "https://your-site.com/webhook"
  }'

Authentication

API requests are authenticated using your API key sent in the Authorization header. You'll have two API keys:

Invoices

An invoice represents a payment request. Create an invoice when your customer is ready to pay.

Invoice Lifecycle

Exact Match System

Our gateway uses exact matching to confirm payments. All four conditions must be met:

Webhooks

When a payment is confirmed, expired, or cancelled, we send a POST request with payment details.

Webhook URL Priority

Webhook Payload

{
  "invoice_reference": "ORDER-001",
  "merchant_id": "uuid",
  "status": "confirmed",
  "asset_code": "USDT_TRC20",
  "payout_address": "TXyz...",
  "amount_usdt_exact": "100.0000",
  "tx_hash": "abc123...",
  "metadata": { "orderId": "123" },
  "paid_at": "2024-01-15T14:32:00Z"
}

Signature Verification

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Usage
const signature = req.headers['x-webhook-signature'];
const isValid = verifySignature(req.body, signature, webhookSecret);
if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Create Invoice

Request Body

White Label Options

Enable white labeling to build your own custom payment UI instead of using our hosted checkout.

"whiteLabel": {
  "cancelUrl": "https://...",
  "statusUrl": "https://...",
  "qrData": "TXyz123...",
  "network": "tron",
  "networkLabel": "Tron (TRC20)",
  "title": "Order #12345",
  "description": "Premium subscription"
}

Error Codes

Supported Networks

Cancel Invoice

Cancel a pending invoice. Only invoices with pending status can be cancelled.

curl -X POST https://api.example.com/api/v1/invoices/{invoice_id}/cancel \
  -H "Authorization: Bearer test_your_api_key"

White Labeling

Build your own payment experience using our API. Instead of redirecting customers to our hosted payment page, you can create a fully branded checkout flow on your own domain.

How It Works

Key Fields for Custom UI

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "ORDER-12345",
  "assetCode": "USDT_TRC20",
  "payoutAddress": "TXyz123...abc456",  // Display & QR code
  "amountUsdtExact": "150.0000",       // Exact amount to pay
  "status": "pending",
  "expiresAt": "2024-01-15T15:00:00Z",  // Countdown timer
  "createdAt": "2024-01-15T14:30:00Z"
}

Status Polling

// Poll every 5-10 seconds until status changes
GET /api/v1/invoices/:id

// Check response.status:
"pending"   → Keep polling, show countdown
"confirmed" → Payment received! Show success
"expired"   → Invoice expired, offer retry
"cancelled" → Invoice was cancelled

Sandbox Mode

Test your integration without real blockchain transactions using sandbox mode.

Test vs Live API Keys

Simulate Payment

In sandbox mode, use the simulate endpoint to mark an invoice as paid:

POST /api/v1/sandbox/invoices/:id/simulate-payment
Authorization: Bearer test_your_api_key

// Response
{
  "success": true,
  "message": "Payment simulated successfully",
  "invoice": {
    "id": "...",
    "status": "confirmed",
    "txHash": "sandbox_tx_abc123..."
  }
}

Best Practices