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

# 全球账户

> 统一查看法币与稳定币账户、可用余额、冻结余额及待结算资金。

一个商户一套多币种账户，法币与稳定币放在同一个账本里查看。

全球账户是 StablePay 为每个商户开立的多币种账户体系。开通后商户即拥有系统默认的结算账户，也可以按业务需要开立更多账户。每个账户只承载一个币种：法币使用 ISO 4217 代码（USD、SGD、EUR），稳定币使用资产代码（USDT、USDC）。因此「账户」是「一个币种加一份余额」的最小单位，跨币种操作一定发生在账户之间，或账户与外部之间。

站在商户的视角，全球账户回答三个问题：钱收进来落在了哪个币种账户、现在有多少能动、还有多少在路上。前两个问题由账户余额回答，第三个由待结算余额回答，两者口径不同，不能相互加总。

## 适用场景

* 跨境收款后希望资金留在多币种账户里，需要时再换汇或对外打款。

* 需要在自有系统里展示商户侧或终端客户侧的可动用余额。

* 需要把可用余额与待结算资金分开对账，避免把在途资金当成可提现金额。

* 多条业务线或多店铺希望用不同账户隔离资金用途。

* 财务需要一份按币种的资金分布，用于资金调度与报表。

## 账户模型

账户由账户编号 `account_no` 标识，是 8 位数字字符串，必须保留前导零（例如 00000001），不要按整数存储或比较。开通时系统自动创建默认结算账户，`is_system_default` 为 true；商户自行开立的账户该字段为 false。editable 表示账户展示名称是否允许商户修改，当前查询接口不提供改名能力。

账户状态有两个取值：active 为正常，restricted 为受限。受限账户仍然可以查询，是否允许资金操作由对应的业务接口判断，而不是由账户状态直接拒绝查询。

账户归属于凭证所属的商户，不同商户的账户天然隔离。商户 App 的请求天然限定在本商户；服务商 App 经商户授权后，可在查询时传 `merchant_id` 指定作用商户，未授权或无权访问时返回 403 `permission_denied`。

## 余额口径

每个账户返回三段金额，全部是账本最小单位的整数：

| 字段 | 口径 | 能否直接使用 | 说明 |
| :- | :- | :- | :- |
| `available_amount` | 可用余额：已完成入账且未被占用的资金 | 是 | 可直接用于换汇、账户划转与提现 |
| `frozen_amount` | 冻结余额：处理中的交易占用、或风控冻结的资金 | 否 | 冻结解除后转为可用余额 |
| `total_amount` | 账户总余额 | 否 | 当前版本等于 `available_amount` + `frozen_amount` |

账户余额只包含可用与冻结两部分；已归因到商户但尚未完成入账的资金不在账户余额内，请通过待结算余额查看，不要把账户余额当作全貌。

金额精度统一为 2 位小数：法币（1050 表示 10.50 USD），USDT、USDC（125000 表示 1,250.00 USDC）。换算展示值时按 100 相除，不要按 1000000 处理。

## 待结算余额

待结算余额是商户维度、按币种汇总的一个数字，与具体账户无关，也不会返回 `account_no`。它表示待结算账户上属于该商户的账面净额，允许为负值；负值反映账务净额方向，客户端应原样展示，不要截断为 0，也不要当成接口错误。

这个数字既不是可用余额，也不是可提现金额，更不能加到某个账户的 `total_amount` 上。该数字按待结算账户的总余额汇总，其中包含被冻结的部分，因此不能理解为「已扣除冻结后可用于结算的金额」。无待结算记录的币种不返回，全部为零时返回空数组。

## 资金怎么进来、怎么出去

全球账户本身是账本视图，资金动作由对应的业务接口完成。下表按商户关心的问题列出各条资金路径与可用的查询和通知方式。

| 能力 | 商户看到什么 | 查询与通知 |
| :- | :- | :- |
| 法币收款 | 本地清算账户信息与归因码，汇款到账后自动归因到商户 | 法币充值记录、`fiat_deposit.credited` 事件 |
| 稳定币收款 | 按「币种 + 网络」生成的入金地址，链上确认后入账 | 稳定币充值记录、deposit.completed 事件 |
| 打款 | 向外部钱包提现，地址与网络取自预建收款人，金额由商户指定 | 收款人、提现记录与提现状态事件 |
| 账户划转 | 同一商户下同币种账户之间的划转 | 划转记录、`account_transfer.completed` 事件 |
| 事件 | 上述动作的实时推送 | Webhook 推送（`X-StablePay-Event-Type` / `X-StablePay-Event-ID`） |

上表中的能力都通过对应的接口与事件提供，字段级定义见[全球账户 API 文档](https://docs.stablepayfi.ai/zh/api/global-accounts/overview)。换汇类操作（法币兑换稳定币、稳定币兑换法币、稳定币互换）属于稳定币兑换产品，见[稳定币兑换产品文档](https://docs.stablepayfi.ai/zh/product/Stablecoin-Exchange.md)与[稳定币兑换 API 文档](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/overview)。接口开通范围与可用币种请联系客户成功团队确认。

## 数据一致性与对账

余额查询返回的 `as_of` 是本次查询的数据库观察时间，不是数据版本号，也不保证多次请求处于同一快照。两次请求之间余额发生变化是正常的，以账本记录为准；不要用 `as_of` 做版本比较或判断数据新旧。

对账时的稳妥做法是：先取一次账户余额与 `as_of`，再拉取同一时间窗内的事件或资金记录，两者对齐后再确认差异。事件推送可能重复送达，需按事件 ID 幂等去重；推送重试间隙内的遗漏可以用余额查询与资金记录核对补齐。相关机制见 Webhook 通知。

推荐的处理顺序：收到 Webhook 后按事件 ID 去重并落到自己的流水表，再用 `GET /account/{account_no}` 或对应记录查询确认最终状态；对账任务按固定周期（例如每小时）比对账户余额快照与流水，差异超过阈值再人工介入。事件只用于触发，余额与记录才是最终依据。

## 与其他产品的关系

全球账户回答的是「钱放在哪」，收银台、二维码支付、收款链接回答的是「钱怎么收进来」。一笔收款成功后，资金最终体现在对应币种账户的余额上；退款走原支付产品的退款能力，对外付款走 Payouts 或全球账户的打款能力。因此把全球账户接进财务系统时，只需要关心账户与币种的映射，不必关心收款渠道。

## 权限与安全

API Key 与 Secret Key 在商户后台按店铺创建，属于店铺级凭证；调用只读接口同样需要完整的鉴权与签名三件套，不能因为「只是查询」而省略签名。Secret Key 只保存在服务端，不要出现在前端代码、日志或客户端存储中。生成 Key、签名算法与请求头的完整说明见 集成前准备。

商户范围由凭证决定：商户 App 天然限定在本商户，服务商 App 只能在已授权范围内传 `merchant_id` 指定作用商户，返回 403 `permission_denied` 说明该 App 无权访问目标商户。返回 401 通常是 Key 缺失、无效或已吊销；返回 404 则说明账户编号不存在或不属于目标商户。

## 常见问题

| 问题 | 说明 |
| :- | :- |
| 金额单位是什么？ | 账本最小单位整数。法币与 USDT、USDC 统一 2 位小数，除以 100 得到展示值。 |
| 为什么 `total_amount` 不等于可提现金额？ | 总余额包含冻结部分，只有 `available_amount` 可以直接动用。 |
| 在途资金在哪里看？ | 账户余额不含在途资金，请通过待结算余额查询。 |
| 待结算余额可以是负数吗？ | 可以。它反映待结算账户的净额方向，客户端应原样保留，不要截断为零。 |
| 能把待结算余额加到账户余额上吗？ | 不能。两者口径不同，待结算是商户维度的独立汇总，与 `account_no` 无关。 |
| `account_no` 能用整数保存吗？ | 不能。它是 8 位字符串，必须保留前导零。 |
| 账户列表支持分页或筛选吗？ | 不支持。接口一次返回当前商户的全部账户，也不提供业务筛选条件。 |
| 受限账户还能查询吗？ | 能。受限账户仍会返回余额，是否允许资金操作由对应业务接口判断。 |
| 需要更多币种或更多账户怎么办？ | 账户与币种的开通由平台配置，请联系客户成功团队。 |

## 相关页面

* [全球账户产品文档](https://docs.stablepayfi.ai/zh/product/Global-Accounts.md)
* [全球账户 API 文档](https://docs.stablepayfi.ai/zh/api/global-accounts/overview)
* [稳定币兑换产品文档](https://docs.stablepayfi.ai/zh/product/Stablecoin-Exchange.md)
* [稳定币兑换 API 文档](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/overview)
* [集成前准备](https://docs.stablepayfi.ai/zh/api/getting-started.md)
* [Webhook 通知](https://docs.stablepayfi.ai/zh/api/webhook-notifications.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.