TopUP 开放 API

第 1 版。"接口详情"里的每个字段都由自动测试和实际接口逐一核对，文档和接口不会不一致。

概览

• 网络和币种：只支持 TRON 上的 USDT（TRC20）。金额用字符串表示，最多 6 位小数，例如 "100.5"。
• 接口地址：https://{BASE_URL}/api/v1/，所有路径都以 "/" 结尾。不带结尾斜杠的请求会被跳转，有些 HTTP 工具在 POST 被跳转时会出错。
• 按客户收款：你的每个客户有一个永久地址（发到账通知）。开启订单模式后，可以给客户创建订单，系统自动把到账匹配到订单（发订单匹配通知）。
• 到账达到 19 个确认（大约 1 分钟）后才算入账，一般在付款后 2 分钟内发出回调。
• 每一笔提币都经过人工审核。工作时间为东八区 8:00–23:00：工作时间内的申请 1 小时内处理，其余的顺延到下一个工作时间。

请求签名

每个请求都要带上三个请求头。Secret 在商户后台的"API 设置"里生成，只显示一次，请只保存在你的服务器上。

Node.js

import crypto from 'node:crypto';

const BASE = process.env.TOPUP_BASE || 'https://{BASE_URL}/api/v1/';
const KEY = process.env.TOPUP_KEY, SECRET = process.env.TOPUP_SECRET;

async function topup(method, path, body) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const raw = body ? JSON.stringify(body) : '';
  const bodyHash = crypto.createHash('sha256').update(raw).digest('hex');
  const url = new URL(path, BASE);
  const toSign = [ts, method, url.pathname + url.search, bodyHash].join('\n');
  const sig = crypto.createHmac('sha256', SECRET).update(toSign).digest('hex');
  const res = await fetch(url, {
    method,
    headers: {
      'content-type': 'application/json',
      'X-TopUP-Key': KEY, 'X-TopUP-Timestamp': ts, 'X-TopUP-Signature': sig,
      ...(method === 'POST' ? { 'Idempotency-Key': crypto.randomUUID() } : {}),
    },
    body: raw || undefined,
  });
  return res.json();
}

const order = await topup('POST', 'orders/', { customer_id: 'user_88213', merchant_order_no: `ACME-${Date.now()}`, amount: '100.00' });
console.log(order.pay_url);

Python

import hashlib, hmac, json, os, time, uuid, requests

BASE = os.environ.get("TOPUP_BASE_URL", "https://{BASE_URL}")
KEY, SECRET = os.environ["TOPUP_KEY"], os.environ["TOPUP_SECRET"].encode()

def topup(method, path, body=None):
    ts = str(int(time.time()))
    raw = json.dumps(body, separators=(",", ":")) if body else ""
    body_hash = hashlib.sha256(raw.encode()).hexdigest()
    to_sign = "\n".join([ts, method, "/api/v1/" + path, body_hash])
    sig = hmac.new(SECRET, to_sign.encode(), hashlib.sha256).hexdigest()
    headers = {"content-type": "application/json", "X-TopUP-Key": KEY,
               "X-TopUP-Timestamp": ts, "X-TopUP-Signature": sig}
    if method == "POST":
        headers["Idempotency-Key"] = str(uuid.uuid4())
    return requests.request(method, BASE + "/api/v1/" + path, data=raw or None, headers=headers).json()

print(topup("GET", "balance/"))

订单收款

POST /api/v1/orders/
{
  "customer_id": "user_88213",          // required: your own ID for this customer
  "customer_name": "Lin Trading",       // optional, used only if the customer is new
  "customer_email": "lin@lintrading.example",
  "merchant_order_no": "ACME-88513",
  "amount": "100.00"
}

{
  "order_no": "ORD-20260929-0413",
  "merchant_order_no": "ACME-88513",
  "customer_id": "user_88213",
  "amount": "100.00",
  "matched": "0.00",
  "address": "TMa7yK2d9Qp4XvB8sN1cF6rH3wZ5jL0eUt",   // the customer's permanent address
  "network": "TRON",
  "token": "USDT",
  "status": "pending",
  "created_at": "2026-09-29T09:00:00.000Z",
  "expires_at": "2026-09-29T09:30:00.000Z",
  "deposits": [],
  "pay_url": "https://{BASE_URL}/pay/ORD-20260929-0413/"
}

• customer_id 必填；新的 customer_id 会自动创建客户和永久地址。merchant_order_no 在你的账户里不能重复。
• 过期时间和匹配阈值由平台为你的账户设置（在"API 设置"里可以看到）。创建订单需要开启订单模式，否则返回 403 order_mode_disabled。
• 可以把 pay_url 发给付款方，也可以自己展示收款地址。
• 如果创建时就匹配到了这个客户之前的到账，返回的状态可能已经是 completed，见"匹配规则"。

客户

POST /api/v1/customers/
{ "customer_id": "user_88213", "name": "Lin Trading", "email": "lin@lintrading.example" }

→ {
  "customer_id": "user_88213", "name": "Lin Trading", "email": "lin@lintrading.example", "remark": "",
  "address": "TXk8fQ2m9sR7ZcY1hN4vB6pW3aLd5Z3wQe",
  "total": "0.00", "count": 0, "fees": "0.00", "unmatched": "0.00",
  "last_payment_at": null, "created_at": "2026-09-11T02:10:00.000Z"
}

• 每个客户一个永久地址，转到这个地址的钱都算这个客户的，不论有没有订单。customer_id 不能修改。
• 低于 1 USDT 的付款不入账、不匹配、不发回调，也不会出现在你的到账明细和导出里（这类付款通常是垃圾"灰尘"转账）。
• customers/stats/ 返回某个时间段的收款合计、笔数、手续费和未匹配金额。

匹配规则

匹配只是把到账和订单关联起来，不会改变余额；只在同一个客户内部进行，两个方向都会触发：

• 订单在先、到账在后：到账匹配给"加上这笔后累计落在下限 L 和上限 H 之间"的未完成订单；都不满足时，匹配最早创建的未完成订单。
• 到账在先、订单在后：从回看时间内最早的未匹配到账开始累计，达到 L 且不超过 H 时匹配，否则一笔都不匹配。
• 状态：累计 < L 为 partial（继续等待），L ≤ 累计 ≤ H 为 completed，累计 > H 为 overpaid；过期时还没达到 L 的订单变为 expired（没有收到）或 expired_partial。
• 过期后才到的钱记为未匹配，需要时用 orders/match/ 手动匹配。尽量不要让同一个客户同时有两个金额接近的未完成订单。

余额与账本

GET balance/ 返回 { "available": "48215.40", "frozen": "1002.00" }。账本只追加，每条记录的类型为 deposit、fee_in、freeze、unfreeze、withdraw、fee_out 之一。列表用 cursor 翻页。

提币

POST /api/v1/withdrawals/
{
  "kind": "payout",              // "payout" = to your customer, "cashout" = to your registered wallet
  "customer_id": "user_88213",   // optional, for payouts
  "to": "TXk8fQ2m9sR7ZcY1hN4vB6pW3aLd5Z3wQe",
  "amount": "1000.00",
  "merchant_ref": "PAYOUT-7781"
}

→ {
  "withdrawal_no": "WD-20260929-7F3A21", "kind": "payout", "customer_id": "user_88213",
  "to": "TXk8fQ2m9sR7ZcY1hN4vB6pW3aLd5Z3wQe", "amount": "1000.00", "fee": "2.00",   // 1002.00 is frozen
  "status": "pending", "txid": null, "reason": null, "merchant_ref": "PAYOUT-7781", "source": "api",
  "created_at": "2026-09-29T09:12:00.000Z"
}

• API 提币需要先在"API 设置"里设置 IP 白名单；没有白名单时返回 403 ip_not_allowed。
• 提交时冻结"金额 + 手续费"，被驳回或取消时解冻。
• 状态：pending → approved → broadcast → completed，或 rejected / cancelled / failed。每次变化都发 withdrawal.updated 回调。

回调

POST https://your-server.example/callback
X-TopUP-Timestamp: 1790665800
X-TopUP-Signature: 5f1c…

{
  "id": "evt_9f2a02",
  "type": "order.matched",       // deposit | order.matched | withdrawal.updated
  "created_at": "2026-09-29T09:10:03Z",
  "data": {
    "order_no": "ORD-20260929-0409",
    "merchant_order_no": "ACME-88509",
    "customer_id": "user_88213",
    "status": "completed",       // pending | partial | completed | overpaid | expired | expired_partial
    "amount": "500.00",
    "matched": "500.00",
    "created_at": "2026-09-29T09:05:00.000Z",
    "expires_at": "2026-09-29T09:35:00.000Z",
    "deposits": [{ "id": "1042", "txid": "a3c1…", "amount": "500.00", "matched_by": "deposit", "time": "2026-09-29T09:10:00.000Z" }],
    "manual": false
  }
}

签名：hex( HMAC-SHA256( Secret, 时间戳 + "\n" + 原始请求体 ) )。收到后请返回任意 2xx 状态码；否则我们在第一次发送之后的 1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时、24 小时重试，然后停止，你可以在商户后台手动重发。同一个事件可能收到不止一次，请按 id 去重。

import crypto from 'node:crypto';

// Verify a TopUP callback. rawBody must be the exact request body you received,
// not an object you parsed and serialised again.
export function verifyCallback(secret, timestamp, signature, rawBody) {
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}\n${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(String(signature || ''));
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express example:
// app.post('/callback', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verifyCallback(SECRET, req.get('X-TopUP-Timestamp'), req.get('X-TopUP-Signature'), req.body)) return res.sendStatus(401);
//   const event = JSON.parse(req.body); // the same event may arrive more than once: deduplicate by event.id
//   res.sendStatus(200);
// });

回调内容

deposit

客户地址收到 1 USDT 及以上的付款并入账。data 的字段：

order.matched

订单因为匹配或解除匹配发生变化。data 的字段：

withdrawal.updated

提币创建或状态变化。data 的字段：

接口详情

金额是 USDT 的字符串（例如 "100.50"），时间是 UTC 的 ISO 8601 格式。列表接口返回 { items, next_cursor }：把 next_cursor 作为 cursor 传入，取下一页。

OrderDeposit

订单里 deposits 数组的每一项。

错误码

出错时返回 { "error": { "code": "…", "message": "…", "field": "…" } }。

沙箱

暂时不提供沙箱。试用阶段请在正式环境用小金额（例如 1 USDT）联调。