跳转到主要内容

​
概述

GatePay 提供多种对账工具，用于保障账户准确性：
  • 余额查询：按币种返回实时可用余额
  • 订单手续费查询：按订单核验手续费和结算金额
  • 资金流水查询：按交易跟踪所有资金变动
有关请求头、签名规则和回调验签，请参见 认证与安全。

​
余额查询

余额查询接口可按币种返回商户支付账户的可用余额。对于结算、出款和风控决策，应以实时查询结果为准。

​
常见使用场景

  • 结算前校验：发起结算前确认可用余额
  • 期末余额快照：在营业结束时记录余额，用于会计核对
  • 运营监控：实时余额告警与阈值监控
  • 多币种管理: 跟踪不同币种的余额

​
API 参考

接口: GET /v1/pay/balance/query 机构接口: POST /payment/open/institution/v1/balance

​
请求参数

参数类型必填说明
currencies数组否要查询的币种代码列表 （例如 [“USDT”, “BTC”, “USD”])
如果未指定币种，API 会返回账户中所有币种的余额.

​
响应字段

字段类型说明
currency字符串币种代码
available字符串可立即使用的余额
hold字符串因待处理订单或出款被冻结的金额
total字符串总余额 (可用余额 + 冻结金额)
last_updated时间戳最近一次余额更新时间

​
请求示例

curl -X GET "https://api.gatepay.io/v1/pay/balance/query?currencies=USDT,BTC,USD" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1704067200000" \
  -H "X-GatePay-Nonce: abc123def456" \
  -H "X-GatePay-Signature: your_signature" \

​
响应示例

{
  "data": [
    {
      "currency": "USDT",
      "available": "10500.50",
      "hold": "499.50",
      "total": "11000.00",
      "last_updated": 1704067205000
    },
    {
      "currency": "BTC",
      "available": "0.25",
      "hold": "0.05",
      "total": "0.30",
      "last_updated": 1704067205000
    },
    {
      "currency": "USD",
      "available": "25000.00",
      "hold": "0.00",
      "total": "25000.00",
      "last_updated": 1704067205000
    }
  ]
}

​
接入步骤

  1. 使用以下接口调用余额查询 API： GET /v1/pay/balance/query 并传入需要查询的币种
  2. 按币种将余额存储到商户本地会计系统
  3. 与本地记录比对以识别差异
  4. 如果余额低于运营最低值，则触发阈值告警

​
订单手续费查询

订单手续费查询 API 可在单笔订单级别提供详细手续费明细和结算金额。可用于财务对账和异常排查。

​
常见使用场景

  • 财务对账: 验证手续费是否符合商户预期
  • 多笔或部分支付: 核对复杂订单场景
  • 异常排查: 识别手续费异常或差异
  • 结算确认: 发起出款前确认金额

​
API 参考

接口: GET /api/open/v1/pay/order/fee/query

​
请求参数

参数类型必填说明
orderId字符串有条件GatePay 订单 ID
merchant_order_no字符串有条件商户生成的订单号
请传入 orderId 或 merchant_order_no（至少传入一个）。

​
响应字段

字段类型说明
orderId字符串GatePay 订单 ID
merchant_order_no字符串商户 订单号
orderAmount字符串原始订单金额
payAmount字符串客户支付金额
settlementAmount字符串入账到商户账户的金额
gatewayFee字符串GatePay 处理手续费
networkFee字符串区块链网络手续费 (如适用)
discountAmount字符串已应用的折扣或返佣
currency字符串结算币种
status字符串订单状态
created_at时间戳订单创建时间
settled_at时间戳结算完成时间

​
请求示例

curl -X GET "https://api.gatepay.io/api/open/v1/pay/order/fee/query?merchant_order_no=ORDER_12345" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1704067200000" \
  -H "X-GatePay-Nonce: abc123def456" \
  -H "X-GatePay-Signature: your_signature" \

​
响应示例

{
  "data": {
    "orderId": "ORD_abc123",
    "merchant_order_no": "ORDER_12345",
    "orderAmount": "1000.00",
    "payAmount": "1000.00",
    "settlementAmount": "980.00",
    "gatewayFee": "20.00",
    "networkFee": "0.00",
    "discountAmount": "0.00",
    "currency": "USDT",
    "status": "SETTLED",
    "created_at": 1704067200000,
    "settled_at": 1704067800000
  }
}

​
接入步骤

  1. 使用以下接口调用订单手续费查询 API： GET /api/open/v1/pay/order/fee/query 并传入订单标识
  2. 将查询结果与本地订单主数据一并存储
  3. 将结算金额与预期值比对
  4. 如果手续费结构不同，则标记差异以便人工复核

​
资金流水查询

资金账本查询可提供商户账户所有资金流入和流出的完整交易历史，是审计追踪和全面对账的关键。

​
常见使用场景

  • 日终对账: 汇总当天所有资金变动
  • 审计追踪: 跟踪资金来源和去向以满足合规要求
  • 异常排查: 识别时间差问题或缺失交易
  • 财务报表: 按类型和币种生成详细流水报表

​
API 参考

接口: GET /v1/pay/bill/orderlist 机构接口: GET /payment/open/institution/v1/pay/bill/orderlist

​
请求参数

参数类型必填说明
start_time时间戳否时间范围开始时间（UTC 毫秒）
end_time时间戳否时间范围结束时间（UTC 毫秒）
page整数否分页页码（从 1 开始，默认 1）
limit整数否每页记录数（默认 20，最大 100）
currency字符串否按币种代码筛选
type字符串否按交易类型筛选（见下方枚举）
order_id字符串否按关联订单 ID 筛选

​
响应字段

字段类型说明
ledger_id字符串唯一账本记录标识（可作为去重键）
type字符串交易类型（见下方枚举）
currency字符串币种 of 交易
amount字符串交易金额（正数或负数）
balance_before字符串交易前余额
balance_after字符串交易后余额
business_id字符串关联订单、退款、转账或出款 ID
description字符串可读描述
created_at时间戳交易时间戳（UTC 毫秒）
元数据对象附加上下文（例如手续费明细）

​
交易类型枚举

类型方向说明
PAYMENT入账收到客户支付
PAYOUT出账结算至商户银行账户
REFUND出账向客户发起的退款
TRANSFER_IN入账从机构主账户转入的资金
TRANSFER_OUT出账转至子账户或对等账户的资金
CHARGE出账平台佣金或手续费扣除
SWAP中性币种兑换 （可能显示为两条记录）
ADJUSTMENT可变人工调账 (入账或出账)
DEPOSIT入账商户直接充值

​
请求示例

curl -X GET "https://api.gatepay.io/v1/pay/bill/orderlist?start_time=1704067200000&end_time=1704153600000&limit=50" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1704067200000" \
  -H "X-GatePay-Nonce: abc123def456" \
  -H "X-GatePay-Signature: your_signature" \

​
响应示例

{
  "data": [
    {
      "ledger_id": "LED_20240101_001",
      "type": "PAYMENT",
      "currency": "USDT",
      "amount": "500.00",
      "balance_before": "10000.00",
      "balance_after": "10500.00",
      "business_id": "ORD_abc123",
      "description": "Payment from order ORDER_12345",
      "created_at": 1704067200000,
      "元数据": {
        "order_no": "ORDER_12345",
        "payer": "customer@example.com"
      }
    },
    {
      "ledger_id": "LED_20240101_002",
      "type": "REFUND",
      "currency": "USDT",
      "amount": "-100.00",
      "balance_before": "10500.00",
      "balance_after": "10400.00",
      "business_id": "REF_xyz789",
      "description": "Refund for order ORDER_12346",
      "created_at": 1704067800000,
      "元数据": {
        "order_no": "ORDER_12346",
        "reason": "Customer requested"
      }
    },
    {
      "ledger_id": "LED_20240101_003",
      "type": "TRANSFER_OUT",
      "currency": "USDT",
      "amount": "-1000.00",
      "balance_before": "10400.00",
      "balance_after": "9400.00",
      "business_id": "TRN_20240101",
      "description": "Transfer to sub-account",
      "created_at": 1704068400000,
      "元数据": {
        "account_id": "SUB_12345",
        "batch_no": "TRN_20240101"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 3,
    "has_next": false
  }
}

​
接入步骤

  1. 使用以下接口按时间范围分页拉取资金账本记录： GET /v1/pay/bill/orderlist
  2. 使用 ledger_id 作为主要去重键，将账本记录持久化到数据库
  3. 使用 business_id 和 元数据 将账本记录关联到业务订单
  4. 生成对账汇总 按以下维度汇总：:
    • 币种
    • 交易类型
    • 日期或时间分桶
    • 关联业务实体（订单、退款、转账等）
  5. 与本地记录比对以识别差异
  6. 标记未匹配记录 以便排查

​
推荐日终对账流程

请按以下步骤执行完整的每日对账：

​
步骤 1: 获取账户余额快照

GET /v1/pay/balance/query
在营业日结束时存储各币种余额快照 （例如 UTC 23:59). 记录：
  • 可用余额
  • 冻结金额
  • 总余额
  • 快照时间戳

​
步骤 2: 拉取资金账本记录

GET /v1/pay/bill/orderlist?start_time={start_of_day}&end_time={end_of_day}&limit=100
分页获取对账周期内的所有交易，并以 ledger_id 为键存储到本地数据库。

​
步骤 3: 拉取订单手续费和结算金额

对于当天结算的每笔订单： 
GET /api/open/v1/pay/order/fee/query?merchant_order_no={order_id}
存储手续费明细和结算详情。

​
步骤 4: 匹配并核对记录

创建如下结构的对账表：
账本 ID类型币种金额业务 ID已匹配备注
LED_001PAYMENTUSDT+500ORD_123✓与订单匹配
LED_002REFUNDUSDT-100REF_456✓与退款匹配
LED_003TRANSFER_OUTUSDT-1000TRN_789✓机构转账
匹配逻辑:
  • 使用 business_id 将 PAYMENT 账本记录匹配到订单系统
  • 将 REFUND 记录匹配到退款系统
  • 将 TRANSFER_OUT/IN 记录匹配到转账记录
  • 将 PAYOUT 记录匹配到结算记录

​
步骤 5: 生成差异报告

识别未匹配记录：
类别数量详情
缺失账本记录0没有对应账本记录的订单
多余账本记录1没有对应订单的账本记录
金额不匹配0已匹配但金额不同的记录
时间差异2记录在不同日期的条目

​
步骤 6: 执行人工复核

对于每项差异：
  1. 复核账本记录 描述和元数据
  2. 与业务记录关联 (订单, 退款, 转账)
  3. 排查时间差 (当日结算与次日结算)
  4. 记录处理结果 (已匹配、已解释或已升级处理)

​
步骤 7: 输出对账结果

生成正式对账单： 
日终对账报告
Date: 2024-01-01
期初余额 (USDT): 10,000.00
Ending Balance (USDT): 9,900.00

Transactions:
- Payments In: +5,000.00
- Refunds Out: -2,500.00
- Transfers Out: -1,000.00
- Fees Out: -500.00
- Adjustments: -100.00

Calculated Ending Balance: 9,900.00
Actual Ending Balance: 9,900.00
Status: BALANCED ✓

Discrepancies: 0
未匹配记录: 0

​
错误处理与故障排查

​
常见问题

问题原因处理建议
余额与本地记录不一致结算或手续费入账存在时间差5-10 分钟后再次查询，并检查是否存在待处理交易
缺失账本记录入账延迟或查询时间范围不匹配将时间范围扩展 1-2 小时后重试查询
账本记录重复数据库去重失败使用 ledger_id 作为主键防止重复
手续费差异促销、返佣或费率变更与当前费率表比对，并检查是否有调账
有关完整错误码，请参见 错误码与最佳实践。

​
最佳实践

​
数据持久化

  • 主键: 对账本记录使用 ledger_id 以确保幂等性
  • 唯一约束: 对 ledger_id 建立唯一约束以防止重复
  • 索引: 按以下字段建立索引 (created_at, currency, type) 以加快对账查询

​
查询优化

  • 时间范围: 按 24 小时分段查询，以获得更快响应
  • 分页: 使用 limit=100 并逐页遍历，避免超时
  • 过滤条件: 使用 currency 和 type 过滤条件减少结果集

​
告警与监控

  • 阈值告警: 当可用余额低于运营最低值时告警
  • 差异告警: 当对账发现未匹配记录时立即告警
  • 时间差告警: 如果账本记录延迟超过 2 小时则告警
  • 回调失败告警: 如果未在 SLA 内收到预期回调则告警

​
文档与审计

  • 对账日志: 存储带时间戳和用户 ID 的对账结果
  • 差异跟踪: 维护已识别和已解决差异的审计轨迹
  • 费率卡: 记录手续费结构和所有促销调整
  • 结算条款: 记录资金何时以及如何结算到商户账户

​
相关文档