> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 余额

> 余额对账对于保障资金准确性和业务可信度至关重要。本文档介绍余额查询、手续费核验以及资金流水跟踪能力，用于日终和周期性对账。

## 概述

GatePay 提供多种对账工具，用于保障账户准确性：

* **余额查询**：按币种返回实时可用余额
* **订单手续费查询**：按订单核验手续费和结算金额
* **资金流水查询**：按交易跟踪所有资金变动

有关请求头、签名规则和回调验签，请参见 [认证与安全](/essentials/version/100/cn/common/authentication)。

***

## 余额查询

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

### 常见使用场景

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

### API 参考

**接口:** `GET /v1/pay/balance/query`

**机构接口:** `POST /payment/open/institution/v1/balance`

#### 请求参数

| 参数           | 类型 | 必填 | 说明                                      |
| ------------ | -- | -- | --------------------------------------- |
| `currencies` | 数组 | 否  | 要查询的币种代码列表 （例如 \["USDT", "BTC", "USD"]) |

如果未指定币种，API 会返回账户中所有币种的余额.

#### 响应字段

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

#### 请求示例

```bash theme={null}
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" \
```

#### 响应示例

```json theme={null}
{
  "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`        | 时间戳 | 结算完成时间         |

#### 请求示例

```bash theme={null}
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" \
```

#### 响应示例

```json theme={null}
{
  "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`      | 入账 | 商户直接充值           |

#### 请求示例

```bash theme={null}
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" \
```

#### 响应示例

```json theme={null}
{
  "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: 获取账户余额快照

```bash theme={null}
GET /v1/pay/balance/query
```

在营业日结束时存储各币种余额快照 （例如 UTC 23:59). 记录：

* 可用余额
* 冻结金额
* 总余额
* 快照时间戳

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

```bash theme={null}
GET /v1/pay/bill/orderlist?start_time={start_of_day}&end_time={end_of_day}&limit=100
```

分页获取对账周期内的所有交易，并以 `ledger_id` 为键存储到本地数据库。

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

对于当天结算的每笔订单：

```bash theme={null}
GET /api/open/v1/pay/order/fee/query?merchant_order_no={order_id}
```

存储手续费明细和结算详情。

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

创建如下结构的对账表：

| 账本 ID    | 类型            | 币种   | 金额    | 业务 ID    | 已匹配 | 备注    |
| -------- | ------------- | ---- | ----- | -------- | --- | ----- |
| LED\_001 | PAYMENT       | USDT | +500  | ORD\_123 | ✓   | 与订单匹配 |
| LED\_002 | REFUND        | USDT | -100  | REF\_456 | ✓   | 与退款匹配 |
| LED\_003 | TRANSFER\_OUT | USDT | -1000 | TRN\_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` 作为主键防止重复   |
| 手续费差异      | 促销、返佣或费率变更     | 与当前费率表比对，并检查是否有调账         |

有关完整错误码，请参见 [错误码与最佳实践](/essentials/version/100/cn/common/error)。

***

## 最佳实践

### 数据持久化

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

### 查询优化

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

### 告警与监控

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

### 文档与审计

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

***

## 相关文档

* [认证与安全](/essentials/version/100/cn/common/authentication)
* [机构 API](/essentials/version/100/cn/internalflow/institution)
* [通知与回调](/essentials/version/100/cn/common/notification)
* [错误码与最佳实践](/essentials/version/100/cn/common/error)
* [币种兑换与闪兑](/essentials/version/100/cn/internalflow/swap)
* [接入总览](/essentials/version/100/cn/common/overview)