如何接受加密货币支付：自托管基础设施开发者指南

一份完整的、逐步的操作指南，教您通过自托管、非托管网关接受加密货币支付。从 Docker 部署到 webhook 集成——您所需要的一切，让您以零交易手续费开始接受 USDT、USDC 及其他加密资产，并完全掌控您的私钥。

为什么接受加密货币支付？

加密货币支付已从小众实验发展为主流支付通道，每日处理数十亿美元的交易量。对于商家而言，接受加密支付不再是关于投机——而是关于接入一个更快、更便宜、更具包容性的金融系统。以下是企业将加密结账加入支付栈的原因：

自托管 vs 第三方网关

在深入了解设置之前，有必要理解自托管和托管（第三方）加密支付网关之间的优劣权衡。每种模式满足不同需求：

像 XPay Labs 这样的自托管网关适合希望获得最大控制权、最低费用和主权基础设施的开发者及企业。第三方网关适用于偏好全托管解决方案且愿意为便利付费的非技术用户。

前提条件

开始之前，请确保您具备以下条件：

步骤 1：部署核心节点

开始接受加密货币支付的最快方式是使用 Docker Compose。在您的 VPS 上创建一个目录，并将以下内容保存为 docker-compose.yml：

version: '3.8'services:  xpay-gateway:    image: ghcr.io/xpaylabs/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"

运行 docker compose up -d 启动网关。首次启动时，如果未设置 XPAY_SEED_PHRASE，XPay Labs 会生成一个新的 HD 钱包种子，或者从您现有的种子派生地址。网关在 8080 端口上暴露 REST API，并立即开始扫描已配置链上的传入交易。

步骤 2：配置环境变量

网关需要几个环境变量才能运行。在与 docker-compose.yml 相同的目录中创建一个 .env 文件：

# .envXPAY_SEED_PHRASE="abandon abandon apple ... twelve words here"XPAY_HMAC_SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"XPAY_TRON_RPC=https://api.trongrid.ioXPAY_EVM_RPC_ETH=https://eth-mainnet.g.alchemy.com/v2/your_keyXPAY_EVM_RPC_BNB=https://bsc-dataseed.binance.orgXPAY_WEBHOOK_URL=https://api.yourdomain.com/webhooks/xpayXPAY_CONFIRMATIONS=19

步骤 3：生成 API 密钥

在网关运行后，生成一个商户 API 密钥来验证您的支付请求。使用管理端点：

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"]  }'

响应中包含一个以 xpay_live_ 为前缀的 API 密钥。请安全存储此密钥——它将取代所有支付 API 调用的用户名/密码认证。您可以为开发、测试和生产环境生成多个具有不同权限范围的密钥。

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

步骤 4：创建您的第一笔支付

现在您可以创建一笔支付发票。当客户到达结账页面时，您的后端调用此端点：

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"    }  }'

网关响应包含一个从您的种子派生的唯一充值地址、一个发票 ID 以及当前支付状态：

{  "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"}

向您的客户显示充值地址和二维码。网关监控区块链上发往此地址的传入交易。一旦检测到并确认后，它会向您的回调 URL 发送 webhook，并将发票状态更新为"confirmed"。

步骤 5：处理 Webhook 回调

XPay Labs 通过 POST 请求向您的 callback_url 发送支付确认 webhook，并在 X-Signature 请求头中附带 HMAC-SHA256 签名。以下是在 Node.js 中验证和处理负载的方法：

import crypto from 'crypto';// Your HMAC secret from XPAY_HMAC_SECRETconst 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 });}

Webhook 使用指数退避重试机制发送（3 次尝试：10 秒、60 秒、300 秒），直到您的服务器返回 200 OK。使用 payment.id 实现幂等性检查，以防止在重复 webhook 投递时出现双重履约。

支持的链与代币

XPay Labs 开箱即用支持三个区块链生态系统，覆盖绝大多数稳定币和山寨币支付量。每条链都有独特的特点，影响着交易速度、成本和集成方式：

后续步骤

您现在已拥有一个功能完善的自托管加密支付网关。以下是可以进一步探索的内容，以充分利用您的基础设施：