@xpaylabs/node-sdk）将加密支付集成到您的 Node.js 应用程序中。SDK 为 TypeScript 和 JavaScript 提供类型化的 API 绑定，具有自动 HMAC 签名、Webhook 验证和完整的 TypeScript 类型声明。
安装
npm install @xpaylabs/node-sdk
配置
import { XPay } from '@xpaylabs/node-sdk';
const xpay = new XPay({
apiKey: 'your-merchant-token',
apiSecret: 'your-api-secret',
baseUrl: 'http://your-gateway:180',
timeout: 30000,
});
| 选项 | 必填 | 默认值 | 描述 |
|---|---|---|---|
apiKey | 是 | — | 商家令牌 |
apiSecret | 是 | — | 用于 HMAC 签名的 API 密钥 |
baseUrl | 否 | https://api.xpaylabs.com | 网关基础 URL（自托管部署时覆盖此值） |
timeout | 否 | 30000 | 请求超时（毫秒） |
核心 API 方法
创建收款订单
import { XPay } from '@xpaylabs/node-sdk';
const xpay = new XPay({ apiKey: '...', apiSecret: '...', baseUrl: 'http://your-gateway:180' });
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_PENDING':
console.log(`订单 ${(event.data as any).orderId} 已创建，等待支付`);
break;
case 'ORDER_PENDING_CONFIRMATION':
console.log('已检测到支付，等待确认');
break;
case 'ORDER_SUCCESS':
console.log(`订单 ${(event.data as any).orderId} 已完成！`);
// 履行订单
break;
case 'ORDER_EXPIRED':
console.log('订单已过期');
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 请求都会自动包装在包含
sign、timestamp 和 nonce 的 ReqPayload 信封中。