API for Developers | PayGate - Non-Custodial USDT Payment Gateway

Quick Start

Three steps to accept your first payment.

1

Get Your API Keys

Register for an account and get both test and live API keys. Use test_ keys for development.

# Test mode
Authorization: Bearer test_abc123...

# Live mode
Authorization: Bearer live_xyz789...

2

Add Your Wallet

Add your USDT wallet address in the dashboard. Payments go directly to your wallet.

TRC20: TXyz123...
ERC20: 0xabc...
BSC:   0xdef...

3

Create an Invoice

Make a POST request to create an invoice and redirect your customer.

POST /api/v1/invoices
{ "amountUsdt": 100 }

POST

Create Invoice

Create a new invoice for your customer. Returns a payment URL and all invoice details.

Required Fields

amountUsdt

Amount in USDT (min: 0.0001, max 4 decimals)

Required

assetCode

USDT_TRC20, USDT_ERC20, or USDT_BSC

Required

Optional Fields

reference

Unique order ID (max 50 chars). Auto-generated if not provided.

callbackUrl

Webhook URL for payment notification (max 500 chars)

expirySeconds

Invoice validity in seconds (300-7200, default: 1800)

metadata

Custom JSON object returned in webhook

walletId

Specific wallet ID to use (uses default wallet if not provided)

title

Invoice title shown on payment page (max 200 chars). E.g., "Order #12345"

description

Invoice description shown on payment page (max 500 chars)

White Label Fields

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

useWhiteLabel

Set to true to receive extra data for custom UI

returnUrl

URL to redirect after payment (max 500 chars)

Request

curl -X POST https://api.example.com/api/v1/invoices \
  -H "Authorization: Bearer test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsdt": 150.0000,
    "assetCode": "USDT_TRC20",
    "reference": "ORDER-12345",
    "expirySeconds": 1800,
    "callbackUrl": "https://your-site.com/webhook",
    "metadata": { "orderId": "12345" },
    "title": "Order #12345",
    "description": "Premium subscription",

    // White label options (optional)
    "useWhiteLabel": true,
    "returnUrl": "https://your-site.com/thank-you"
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "ORDER-12345",
  "assetCode": "USDT_TRC20",
  "payoutAddress": "TXyz123...abc456",
  "amountUsdtExact": "150.0000",
  "status": "pending",
  "expiresAt": "2024-01-15T15:00:00Z",
  "paymentUrl": "https://pay.example.com/ORDER-12345",
  "createdAt": "2024-01-15T14:30:00Z",
  "isTest": true,
  "metadata": { "orderId": "12345" },

  // Only included when useWhiteLabel: true
  "whiteLabel": {
    "cancelUrl": "https://pay.example.com/ORDER-12345/cancel",
    "statusUrl": "https://pay.example.com/ORDER-12345/status",
    "qrData": "TXyz123...abc456",
    "network": "tron",
    "networkLabel": "Tron (TRC20)",
    "expiresAt": "2024-01-15T15:00:00Z",
    "title": "Order #12345",
    "description": "Premium subscription"
  }
}

Webhook Payload

{
  "invoice_reference": "ORDER-12345",
  "merchant_id": "550e8400-e29b-41d4-a716...",
  "status": "confirmed",
  "asset_code": "USDT_TRC20",
  "payout_address": "TXyz123...abc456",
  "amount_usdt_exact": "150.0000",
  "tx_hash": "abc123...def789",
  "metadata": {
    "orderId": "12345",
    "customerId": "user-001"
  },
  "paid_at": "2024-01-15T14:32:00Z"
}

Headers

Content-Type: application/json
X-Webhook-Signature: hmac_sha256_signature
X-Webhook-Id: webhook-log-uuid
X-Invoice-Reference: ORDER-12345

WEBHOOK

Payment Confirmation

When a payment is confirmed on the blockchain, we send an HMAC-signed webhook to your callback URL.

Signature Verification

Always verify the webhook signature before processing. The signature is an HMAC-SHA256 hash of the JSON body using your webhook secret.

Node.js Example

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)
  );
}

Important

Return HTTP 200 within 30 seconds to acknowledge receipt. Failed webhooks are retried with exponential backoff up to 10 times.

SANDBOX

Test Mode & Sandbox API

Develop and test your integration without real blockchain transactions. Use your test_ API key to create test invoices, then simulate payments using the sandbox API.

How It Works

1 Create invoices using your test_ API key
2 Simulate payment using the sandbox endpoint
3 Receive webhook just like production

Test vs Live Keys

test_ keys create test invoices that can be simulated. live_ keys create real invoices that require actual blockchain payments.

Simulate Payment

# Simulate a successful payment
curl -X POST https://api.example.com/api/v1/sandbox/simulate-payment \
  -H "Authorization: Bearer test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "delaySeconds": 0
  }'

Sandbox Endpoints

POST /api/v1/sandbox/simulate-payment
  - invoiceId (required): Invoice to mark as paid
  - delaySeconds (optional): Delay before confirming

POST /api/v1/sandbox/trigger-expiry
  - invoiceId (required): Invoice to expire

POST /api/v1/sandbox/test-webhook
  - url (optional): Custom URL to test
  - invoiceId (optional): Use real invoice data

Other Endpoints

Additional API endpoints for invoice and account management.

GET /api/v1/invoices/:id

Get Invoice by ID

Retrieve invoice details by UUID.

curl -H "Authorization: Bearer test_key" \
  https://api.example.com/api/v1/invoices/uuid

GET /api/v1/invoices/reference/:ref

Get Invoice by Reference

Retrieve invoice using your order reference.

curl -H "Authorization: Bearer test_key" \
  https://api.example.com/api/v1/invoices/reference/ORDER-123

GET /api/v1/invoices

List All Invoices

Get all invoices for your merchant account with pagination.

curl -H "Authorization: Bearer test_key" \
  "https://api.example.com/api/v1/invoices?page=1&limit=20"

POST /api/v1/invoices/:id/cancel

Cancel Invoice

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

curl -X POST -H "Authorization: Bearer test_key" \
  https://api.example.com/api/v1/invoices/uuid/cancel

GET /api/v1/account

Get Account Info

Retrieve your merchant account details and statistics.

curl -H "Authorization: Bearer test_key" \
  https://api.example.com/api/v1/account

GET /api/v1/account/api-logs

Get API Logs

Retrieve your recent API request logs for debugging.

curl -H "Authorization: Bearer test_key" \
  "https://api.example.com/api/v1/account/api-logs?limit=50"

WHITE LABEL

Custom Payment Pages

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

1 Create an invoice via API and get the payment details
2 Display the wallet address, amount, and QR code on your own page
3 Poll the status endpoint or wait for webhook confirmation

Full Customization

Use your own branding, colors, and domain. Your customers never see our interface. The API provides all data needed: address, exact amount, network info, and expiry time.

Invoice Response (White Label)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "ORDER-12345",
  "assetCode": "USDT_TRC20",
  "payoutAddress": "TXyz123...abc456",
  "amountUsdtExact": "150.0000",
  "status": "pending",
  "expiresAt": "2024-01-15T15:00:00Z",
  "paymentUrl": "https://pay.example.com/ORDER-12345",
  "createdAt": "2024-01-15T14:30:00Z",
  "isTest": false,
  "metadata": { "orderId": "12345" },

  // Only included when useWhiteLabel: true
  "whiteLabel": {
    "cancelUrl": "https://pay.example.com/ORDER-12345/cancel",
    "statusUrl": "https://pay.example.com/ORDER-12345/status",
    "qrData": "TXyz123...abc456",
    "network": "tron",
    "networkLabel": "Tron (TRC20)",
    "expiresAt": "2024-01-15T15:00:00Z",
    "title": "Order #12345",
    "description": "Premium subscription"
  }
}

Poll Status Endpoint

GET /api/v1/invoices/:id

// Poll every 5-10 seconds
// Check response.status:
"pending"   → Keep polling
"confirmed" → Payment received!
"expired"   → Invoice expired

Security & Rate Limits

Keep your integration secure and performant.

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Create Invoice 100 req/min

Get Invoice 300 req/min

List Invoices 60 req/min

Sandbox Endpoints 60 req/min

When rate limited, you'll receive HTTP 429. Check the Retry-After header for wait time.

API Key Security

Your API keys grant full access to your merchant account. Keep them secure at all times.

Separate test and live API keys for safety

Never expose keys in client-side code or version control

Regenerate keys from dashboard if compromised

Tip: Use environment variables to store API keys securely in your server applications.

Webhook Security

Always verify webhook signatures to ensure requests are authentic.

HMAC-SHA256 signature in X-Webhook-Signature

Use timing-safe comparison to prevent attacks

Regenerate webhook secret if compromised

Best Practices

Follow these recommendations for a robust integration.

Store API keys in environment variables, never in code

Use idempotent references to prevent duplicate invoices

Handle webhook retries gracefully (idempotent processing)

Test thoroughly in sandbox before going live

Error Handling

HTTP status codes and error responses.

Code	Description
`200`	Success
`201`	Created - Invoice created successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Account suspended
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Duplicate reference
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Error - Something went wrong

Error Response Format

{
  "statusCode": 400,
  "message": "Amount must have at most 4 decimal places",
  "error": "Bad Request"
}

SDKs & Libraries

Official and community libraries for popular languages.

Node.js

npm install usdt-gateway

Official

Python

pip install usdt-gateway

Coming Soon

PHP

composer require usdt-gateway

Coming Soon

Don't see your language? The REST API works with any HTTP client. Request an SDK

Ready to Integrate?

Create your account now and get your API key instantly.

Get API Key Full Documentation

Developer Documentation

Quick Start

Get Your API Keys

Add Your Wallet

Create an Invoice

Create Invoice

Required Fields

Optional Fields

White Label Fields

Payment Confirmation

Signature Verification

Node.js Example

Important

Test Mode & Sandbox API

How It Works

Test vs Live Keys

Other Endpoints

Get Invoice by ID

Get Invoice by Reference

List All Invoices

Cancel Invoice

Get Account Info

Get API Logs

Custom Payment Pages

How It Works

Full Customization

Security & Rate Limits

Rate Limits

API Key Security

Webhook Security

Best Practices

Error Handling

SDKs & Libraries

Node.js

Python

PHP

Ready to Integrate?