余额 - Gate Pay DOCS

概述

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
    }
  ]
}

接入步骤

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

订单手续费查询

订单手续费查询 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
  }
}

接入步骤

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

资金流水查询

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

常见使用场景

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

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
  }
}

接入步骤

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

账本 ID	类型	币种	金额	业务 ID	已匹配	备注
LED_001	PAYMENT	USDT	+500	ORD_123	✓	与订单匹配
LED_002	REFUND	USDT	-100	REF_456	✓	与退款匹配
LED_003	TRANSFER_OUT	USDT	-1000	TRN_789	✓	机构转账

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

错误处理与故障排查

常见问题

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

有关完整错误码，请参见错误码与最佳实践。

最佳实践

数据持久化

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

查询优化

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

告警与监控

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

文档与审计

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

​概述

​余额查询

​常见使用场景

​API 参考

​请求参数

​响应字段

​请求示例

​响应示例

​接入步骤

​订单手续费查询

​常见使用场景

​API 参考

​请求参数

​响应字段

​请求示例

​响应示例

​接入步骤

​资金流水查询

​常见使用场景

​API 参考

​请求参数

​响应字段

​交易类型枚举

​请求示例

​响应示例

​接入步骤

​推荐日终对账流程

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

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

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

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

​步骤 5: 生成差异报告

​步骤 6: 执行人工复核

​步骤 7: 输出对账结果

​错误处理与故障排查

​常见问题

​最佳实践

​数据持久化

​查询优化

​告警与监控

​文档与审计

​相关文档

概述

余额查询

常见使用场景

API 参考

请求参数

响应字段

请求示例

响应示例

接入步骤

订单手续费查询

常见使用场景

API 参考

请求参数

响应字段

请求示例

响应示例

接入步骤

资金流水查询

常见使用场景

API 参考

请求参数

响应字段

交易类型枚举

请求示例

响应示例

接入步骤

推荐日终对账流程

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

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

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

步骤 4: 匹配并核对记录

步骤 5: 生成差异报告

步骤 6: 执行人工复核

步骤 7: 输出对账结果

错误处理与故障排查

常见问题

最佳实践

数据持久化

查询优化

告警与监控

文档与审计

相关文档