快速接入

如果你只是想先把接入跑通，先看这一页就够了：先生成签名请求头，再调用创建收款订单接口，最后在回调地址里验签并返回 2xx。

下面示例默认使用创建收款订单；创建代付订单时，签名方式、请求头和回调头完全相同，只需要把接口地址和业务参数替换掉。

正式 API 地址https://api.uugate.com

支持币种TRC20-USDT · BEP20-USDT · BEP20-USDC · SPL-USDC

回调准备API Key + notifyUrl

✓准备 Merchant UID。

✓准备商户后台 API 接入中的 mch_ 开头 API Key。

✓准备一个商户自己可公网访问的 notifyUrl，下单时必须传入。

Step 1

生成签名请求头

开放接口请求统一使用 x-api-key、x-merchant-uid、x-timestamp、x-nonce、x-signature 这 5 个请求头。

x-api-key 和签名密钥都使用同一串 mch_ 开头 API Key。
签名 path 只写接口路径，例如 /openapi/payin/orders，不要带域名。
签名原文固定为 Merchant UID、timestamp、nonce、method、path、canonical query、canonical body。

最小 Node.js 签名示例

import crypto from 'node:crypto';

const merchantUid = '880001';
const apiKey = 'mch_xxxxxxxxxxxxxxxxxxxx';
const timestamp = String(Date.now());
const nonce = crypto.randomBytes(16).toString('hex');
const method = 'POST';
const path = '/openapi/payin/orders';
const canonicalQuery = '';
const canonicalBody = '{"amount":"100.00","chainCode":"TRON","merchantOrderNo":"M202604170001","notifyUrl":"https://merchant.example.com/api/uugate/payin-notify","tokenSymbol":"USDT"}';

const payload = [
  merchantUid,
  timestamp,
  nonce,
  method,
  path,
  canonicalQuery,
  canonicalBody,
].join('\n');

const signature = crypto.createHmac('sha256', apiKey).update(payload).digest('hex');

Step 2

创建收款订单

签名头准备好后，直接调用创建收款订单接口；成功后重点拿到 orderNo、cashierUrl、paymentUri 三个字段。

接口地址：POST /openapi/payin/orders。
商户前端如果要跳转收银台，直接使用返回的 cashierUrl。
notifyUrl 为必填字段，直接跟下单请求一起传，不需要再去后台单独配置回调地址。
如果要做代付，只需把 path 换成 /openapi/payout/orders，并提交代付参数。

Node.js 创建订单示例

import { UUGateClient } from 'uugate-openapi-sdk';

const client = new UUGateClient({
  baseUrl: 'https://api.uugate.com',
  merchantUid: '880001',
  apiKey: 'mch_xxxxxxxxxxxxxxxxxxxx',
});

const order = await client.createPayinOrder({
  chainCode: 'TRON',
  tokenSymbol: 'USDT',
  merchantOrderNo: 'M202604170001',
  amount: '100.00',
  notifyUrl: 'https://merchant.example.com/api/uugate/payin-notify',
});

console.log(order.orderNo, order.cashierUrl);

Step 3

接收并处理回调

平台回调到你下单时传入的 notifyUrl 后，先用 apiKey 验签，验签通过再更新业务订单，最后返回 200 或其他 2xx。

回调验签使用 apiKey，不使用开放接口的 x-signature。
收款场景建议把 status=completed 视为最终成功。
代付场景建议重点处理 status=confirmed 和 status=failed。

最小回调处理示例

import express from 'express';
import { verifyCallbackSignature } from 'uugate-openapi-sdk';

const app = express();
app.use(express.json({
  verify: (req, _res, buffer) => {
    req.rawBody = buffer.toString('utf8');
  },
}));

app.post('/merchant/callback', (req, res) => {
  const valid = verifyCallbackSignature({
    apiKey: process.env.UUGATE_API_KEY,
    timestamp: req.header('x-callback-timestamp'),
    nonce: req.header('x-callback-nonce'),
    signature: req.header('x-callback-signature'),
    rawBody: req.rawBody || '',
  });

  if (!valid) {
    return res.status(401).json({ ok: false });
  }

  if (req.body.status === 'completed') {
    // 更新商户订单为成功
  }

  return res.status(200).json({ ok: true });
});

收款和代付共用同一套签名算法与回调头，不需要维护两套鉴权逻辑。

如果你已经能看懂这一页，继续往下看详细接口参数、返回结构和 SDK 下载即可。