跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt

Use this file to discover all available pages before exploring further.

使用官方 XPayLabs Node.js SDK(@xpaylabs/node-sdk)将加密支付集成到您的 Node.js 应用程序中。SDK 为 TypeScript 和 JavaScript 提供类型化的 API 绑定,具有自动 HMAC 签名、Webhook 验证和完整的 TypeScript 类型声明。

安装

npm install @xpaylabs/node-sdk
SDK 需要 Node.js 14+。

配置

import { XPay } from '@xpaylabs/node-sdk';

const xpay = new XPay({
  apiKey: 'your-merchant-token',
  apiSecret: 'your-api-secret',
  baseUrl: 'http://your-gateway:3010',
  timeout: 30000,
});
选项必填默认值描述
apiKey商家令牌
apiSecret用于 HMAC 签名的 API 密钥
baseUrlhttps://api.xpaylabs.com网关基础 URL
timeout30000请求超时(毫秒)

核心 API 方法

创建收款订单

import { XPay } from '@xpaylabs/node-sdk';

const xpay = new XPay({ apiKey: '...', apiSecret: '...', baseUrl: 'http://your-gateway:3010' });

async function createPayment(uid: string, amount: number) {
  const collection = await xpay.createCollection({
    amount,
    symbol: 'USDT',
    chain: 'TRON',
    orderId: `order-${Date.now()}`,
    uid,
  });

  return collection.data;
}

创建付款

async function sendPayout(uid: string, amount: number, receiveAddress: string) {
  const payout = await xpay.createPayout({
    amount,
    symbol: 'USDT',
    chain: 'TRON',
    orderId: `payout-${Date.now()}`,
    uid,
    receiveAddress,
  });

  return payout.data;
}

查询订单状态

async function getStatus(orderId: string) {
  const order = await xpay.getOrderStatus(orderId);
  return order.data;
}

获取支持的代币

async function getSymbols() {
  const symbols = await xpay.getSupportedSymbols();
  symbols.forEach(s => {
    console.log(`${s.symbol} on ${s.chain} (decimals: ${s.decimals})`);
  });
}

const filtered = await xpay.getSupportedSymbols('TRON', 'USDT');

处理 Webhook

使用 Express.js 端点接收和验证 Webhook 回调:
import express from 'express';
import { XPay } from '@xpaylabs/node-sdk';

const app = express();
app.use(express.json());

const xpay = new XPay({
  apiKey: process.env.XPAYLABS_MERCHANT_TOKEN!,
  apiSecret: process.env.XPAYLABS_API_SECRET!,
  baseUrl: process.env.XPAYLABS_GATEWAY_URL!,
});

app.post('/webhook', (req, res) => {
  const body = JSON.stringify(req.body);
  const signature = req.body.sign;
  const timestamp = req.body.timestamp.toString();

  const event = xpay.parseWebhook(body, signature, timestamp);

  if (!event) {
    return res.status(400).send('无效的 Webhook 签名或时间戳已过期');
  }

  switch (event.notifyType) {
    case 'ORDER_SUCCESS':
      console.log(`订单 ${(event.data as any).orderId} 已完成!`);
      break;

    case 'ORDER_FAILED':
      console.log(`订单失败:${(event.data as any).reason}`);
      break;

    case 'COLLECT_SUCCESS':
      console.log(`归集完成:${(event.data as any).collectAmount}`);
      break;
  }

  res.status(200).send('Webhook received');
});

app.listen(3000);

错误处理

try {
  const payout = await xpay.createPayout({ /* ... */ });
} catch (error: any) {
  console.error(`错误:${error.message}`);
  console.error(`HTTP 状态:${error.status}`);
  console.error(`错误码:${error.code}`);
}

TypeScript 支持

SDK 附带了完整的类型声明。直接导入类型:
import {
  XPay,
  XPayConfig,
  CollectionRequest,
  PayoutRequest,
  CollectionResponse,
  PayoutResponse,
  OrderDetails,
  SupportedSymbol,
  WebhookEvent,
  OrderWebhookData,
  CollectWebhookData,
  OrderStatus,
  WebhookNotifyType,
} from '@xpaylabs/node-sdk';
SDK 内部自动处理 HMAC-SHA256 签名——您无需手动计算签名。所有 POST 请求都会自动包装在包含 signtimestampnonceReqPayload 信封中。
Last modified on May 31, 2026