跳到主要内容

查询商户余额

查询商户账户的当前结算余额。

接口​

  • 端点：POST {API_BASE}/pay/balance
  • API_BASE：https://api.168tonpay.xyz/api/v1/compat/godapay
  • 认证：请求体 MD5 排序签名

请求体​

参数类型必需描述
merchantIdstring (UUID)✅你的商户 ID
signaturestring✅MD5 排序签名

请求示例​

cURL​

curl -X POST "${API_BASE}/pay/balance" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "aef6025b-...",
    "signature": "<md5-sorted>"
  }'

Node.js​

async function getBalance() {
  const body = { merchantId: process.env.MERCHANT_ID };
  body.signature = sign(body, process.env.API_SECRET); // 见认证页

  const res = await fetch(`${process.env.API_BASE}/pay/balance`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  return res.json();
}

响应示例（200 OK）​

{
  "code": 0,
  "data": {
    "merchantId": "aef6025b-f435-443c-bb18-f10e65d9314c",
    "balance": "25000.00",
    "currency": "BDT"
  }
}
字段类型描述
merchantIdstring (UUID)商户 ID
balancestring结算余额
currencystring货币代码（恒为 BDT）

使用场景​

创建付款订单前检查余额​

const { data } = await getBalance();
if (parseFloat(data.balance) < amount) {
  throw new Error('Merchant balance is insufficient');
}
await createPayout({ /* ... */ });

注意事项​

  • 建议本地缓存 30–60 秒，避免频繁查询（限流 60 req/min）。
  • 创建付款订单前应检查余额，否则会被服务端以 INSUFFICIENT_BALANCE 拒绝。

相关接口​