How to Accept Crypto Payments: A Developer's Guide to Self-Hosted Infrastructure

A complete, step-by-step walkthrough for accepting cryptocurrency payments using a self-hosted, non-custodial gateway. From Docker deployment to webhook integration — everything you need to start accepting USDT, USDC, and other crypto assets with zero transaction fees and full control over your private keys.

Why Accept Crypto Payments?

Cryptocurrency payments have evolved from a niche experiment to a mainstream payment rail processing billions of dollars daily. For merchants, accepting crypto is no longer about speculation — it is about accessing a faster, cheaper, and more inclusive financial system. Here is why businesses are adding crypto checkout to their payment stack:

Self-Hosted vs Third-Party Gateways

Before diving into setup, it is important to understand the tradeoffs between self-hosted and hosted (third-party) crypto payment gateways. Each model serves different needs:

Self-hosted gateways like XPay Labs are ideal for developers and businesses that want maximum control, minimal fees, and sovereign infrastructure. Third-party gateways make sense for non-technical users who prefer a fully managed solution and are willing to pay for convenience.

Prerequisites

Before you begin, ensure you have the following:

Step 1: Deploy the Core Node

The fastest way to start accepting crypto payments is with Docker Compose. Create a directory on your VPS and save the following as docker-compose.yml:

version: '3.8'
services:
  xpay-gateway:
    image: ghcr.io/xpay-labs/gateway:latest
    container_name: xpay_core
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - XPAY_SEED_PHRASE=${XPAY_SEED_PHRASE}
      - XPAY_HMAC_SECRET=${XPAY_HMAC_SECRET}
      - XPAY_TRON_RPC=https://api.trongrid.io
      - XPAY_EVM_RPC=https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}
      - XPAY_WEBHOOK_URL=https://api.yourdomain.com/webhooks/xpay
    volumes:
      - ./data:/app/data
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Run docker compose up -d to start the gateway. On your first launch, XPay Labs generates a new HD wallet seed if XPAY_SEED_PHRASE is not set, or derives addresses from your existing seed. The gateway exposes a REST API on port 8080 and immediately begins scanning configured chains for incoming transactions.

Step 2: Configure Environment

The gateway requires several environment variables to operate. Create a .env file in the same directory as your docker-compose.yml:

# .env
XPAY_SEED_PHRASE="abandon abandon apple ... twelve words here"
XPAY_HMAC_SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
XPAY_TRON_RPC=https://api.trongrid.io
XPAY_EVM_RPC_ETH=https://eth-mainnet.g.alchemy.com/v2/your_key
XPAY_EVM_RPC_BNB=https://bsc-dataseed.binance.org
XPAY_WEBHOOK_URL=https://api.yourdomain.com/webhooks/xpay
XPAY_CONFIRMATIONS=19

Step 3: Generate API Keys

With the gateway running, generate a merchant API key to authenticate your payment requests. Use the admin endpoint:

curl -X POST "http://localhost:8080/v1/admin/api-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${XPAY_ADMIN_TOKEN}" \
  -d '{
    "label": "production-checkout",
    "permissions": ["payments:create", "payments:read"]
  }'

The response includes an API key prefixed with xpay_live_. Store this securely — it replaces username/password authentication for all payment API calls. You can generate multiple keys with different permission scopes for development, staging, and production environments.

// Example response
{
  "id": "key_7f3d9c2a1b",
  "label": "production-checkout",
  "key": "xpay_live_8f3a9d7219bc4e5f6a7b8c9d0e1f2a3b4c5d6e7f",
  "permissions": ["payments:create", "payments:read"],
  "created_at": "2026-05-22T10:30:00Z"
}

Step 4: Create Your First Payment

Now you can create a payment invoice. Your backend calls this endpoint when a customer reaches checkout:

curl -X POST "https://gateway.yourdomain.com/v1/payments" \
  -H "Authorization: Bearer xpay_live_8f3a9d7219bc" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "USDT",
    "chain": "TRON",
    "order_id": "order_783120",
    "callback_url": "https://api.merchant.com/v1/webhooks/xpay",
    "customer_email": "[email protected]",
    "metadata": {
      "product_id": "prod_456",
      "plan": "premium_annual"
    }
  }'

The gateway responds with a unique deposit address derived from your seed, an invoice ID, and the current payment status:

{
  "id": "pay_9f3b8c2a1d",
  "order_id": "order_783120",
  "amount": "100.00",
  "currency": "USDT",
  "chain": "TRON",
  "deposit_address": "TYpSq7f8MubE8bK6vG7m8F7WbA9c3DxE1F",
  "qr_code": "https://gateway.yourdomain.com/v1/qr/pay_9f3b8c2a1d",
  "status": "pending",
  "expires_at": "2026-05-22T11:00:00Z",
  "created_at": "2026-05-22T10:00:00Z"
}

Display the deposit address and QR code to your customer. The gateway monitors the blockchain for incoming transactions to this address. Once detected and confirmed, it sends a webhook to your callback URL and updates the invoice status to "confirmed".

Step 5: Handle Webhook Callbacks

XPay Labs sends payment confirmation webhooks to your callback_url via POST with an HMAC-SHA256 signature in the X-Signature header. Here is how to verify and process the payload in Node.js:

import crypto from 'crypto';

// Your HMAC secret from XPAY_HMAC_SECRET
const HMAC_SECRET = process.env.XPAY_HMAC_SECRET;

export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get('x-signature');

  // Verify HMAC-SHA256 signature
  const expected = crypto
    .createHmac('sha256', HMAC_SECRET)
    .update(body, 'utf8')
    .digest('hex');

  if (signature !== expected) {
    return Response.json({ error: 'invalid signature' }, { status: 401 });
  }

  const payload = JSON.parse(body);

  // payload structure:
  // {
  //   "event": "payment.confirmed",
  //   "payment": {
  //     "id": "pay_9f3b8c2a1d",
  //     "order_id": "order_783120",
  //     "amount": "100.00",
  //     "currency": "USDT",
  //     "chain": "TRON",
  //     "tx_id": "b4f7c3a12d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2",
  //     "from_address": "TXYZ...",
  //     "to_address": "TABC...",
  //     "confirmations": 32,
  //     "status": "confirmed",
  //     "timestamp": 1715875200
  //   }
  // }

  if (payload.event === 'payment.confirmed') {
    // Fulfill the order
    await fulfillOrder(payload.payment.order_id, payload.payment);
    return Response.json({ received: true });
  }

  return Response.json({ received: true });
}

Webhooks are sent with exponential backoff retry (3 attempts: 10s, 60s, 300s) until your server returns a 200 OK. Implement idempotency checks using the payment.id to prevent double-fulfillment in case of duplicate webhook deliveries.

Supported Chains & Tokens

XPay Labs supports three blockchain ecosystems out of the box, covering the vast majority of stablecoin and altcoin payment volume. Each chain has unique characteristics that affect transaction speed, cost, and integration approach:

Next Steps

You now have a fully functional self-hosted crypto payment gateway. Here is what to explore next to get the most out of your infrastructure: