> ## 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.

# 全球账户 API

> 全球账户 API：账户与余额、稳定币充值、提现、账户划转、收款人，共 17 个接口。

版本：v1.0（2026-09-29） · Base URL：`https://api.stablepay.co` · 前缀：`/api/v1` · HTTPS / JSON / UTF-8

## 概述与能力范围

全球账户 API 管理商户的多币种账户与账户级资金进出：查询账户与余额、稳定币充值与提现、同商户账户间划转、收款人管理，以及这些资源的事件推送（Webhook）。所有接口以 /api/v1 为前缀，商户身份由凭证确定：商户 App 不需要传 `merchant_id`，服务商 App 通过 `merchant_id` 指定作用商户。

| 方法 | 路径 | 用途 |
| :- | :- | :- |
| GET | [`/account`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-account) | 查询目标商户的全部账户及余额 |
| GET | [`/account/{account_no}`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-account-account-no) | 查询单个账户及余额 |
| GET | [`/pending_settlement_balance`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-pending-settlement-balance) | 按币种查询待结算余额 |
| GET | [`/fund/deposit_address`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-fund-deposit-address) | 查询稳定币入金地址 |
| GET | [`/fund/deposits`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-fund-deposits) | 稳定币充值记录列表 |
| GET | [`/fund/deposits/{deposit_id}`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-fund-deposits-deposit-id) | 查询单条稳定币充值记录 |
| POST | [`/fund/deposits/{deposit_id}/confirm`](https://docs.stablepayfi.ai/zh/api/global-accounts/post-fund-deposits-deposit-id-confirm) | 回填 Travel Rule 资金来源 |
| POST | [`/fund/withdrawals`](https://docs.stablepayfi.ai/zh/api/global-accounts/post-fund-withdrawals) | 创建提现 |
| GET | [`/fund/withdrawals/{withdrawal_id}`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-fund-withdrawals-withdrawal-id) | 查询提现 |
| POST | [`/fund/account_transfers`](https://docs.stablepayfi.ai/zh/api/global-accounts/post-fund-account-transfers) | 创建账户间划转 |
| GET | [`/fund/account_transfers/{account_transfer_id}`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-fund-account-transfers-account-transfer-id) | 查询账户划转 |
| GET | [`/recipient/requirements`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-recipient-requirements) | 查询收款人字段规则 |
| POST | [`/recipient`](https://docs.stablepayfi.ai/zh/api/global-accounts/post-recipient) | 创建收款人 |
| GET | [`/recipient`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-recipient) | 收款人列表 |
| GET | [`/recipient/{recipient_id}`](https://docs.stablepayfi.ai/zh/api/global-accounts/get-recipient-recipient-id) | 查询收款人 |
| PUT | [`/recipient/{recipient_id}`](https://docs.stablepayfi.ai/zh/api/global-accounts/put-recipient-recipient-id) | 更新收款人 |
| DELETE | [`/recipient/{recipient_id}`](https://docs.stablepayfi.ai/zh/api/global-accounts/delete-recipient-recipient-id) | 删除收款人 |

账户查询接口使用 8 位数字账户编号，列表以 object 与 data 返回；其余接口的业务资源 ID 为 10 位数字。所有涉及账户的参数统一使用 8 位 `account_no`。

## 认证与签名

所有请求携带 API Key 与签名三件套，规则与 StablePay 公共认证规范一致。

| 请求头 | 必填 | 说明 |
| :- | :- | :- |
| Authorization | 是 | Bearer `{api_key}` |
| `X-StablePay-Timestamp` | 是 | Unix 秒，与服务端时间相差不超过 5 分钟 |
| `X-StablePay-Nonce` | 是 | 防重放随机串，16 到 64 个字符，每次请求唯一 |
| `X-StablePay-Signature` | 是 | HMAC-SHA256 签名，小写十六进制 |

签名串为 `{timestamp}.{nonce}.{requestBody}`。GET 与 DELETE 没有请求体，`{requestBody}` 取空字符串，签名串以点号结尾；POST 与 PUT 使用实际发送的原始 JSON 字符串，计算签名后不要再重排字段或格式化。完整算法与多语言示例见 集成前准备。

凭证属于 App：商户 App 对应单一商户，请求不带 `merchant_id`；服务商 App 经商户授权后可服务多个商户，可在账户与余额查询、资金与收款人接口的 Query 或 Body 中传 `merchant_id` 指定作用商户。未授权或无权访问目标商户时返回 403 `permission_denied`。签名密钥只保存在服务端，重试时必须重新生成 timestamp 与 nonce。

## 数据约定

| 项目 | 约定 | 示例 |
| :- | :- | :- |
| 资源 ID | `xxx_id` 一律为 10 位数字字符串：`merchant_id`、`deposit_id`、`withdrawal_id`、`account_transfer_id`、`recipient_id`、`event_id`、`request_id` | "9000000070" |
| 账户编号 | `account_no` 为 8 位数字字符串，前导零有含义；所有涉及账户的请求参数与响应字段都使用该编号 | "00000001" |
| 金额 | 整数，为该币种最小单位；法币与 USDT、USDC 统一为 2 位小数 | 1050 表示 10.50 USD；125000 表示 1,250.00 USDC |
| 币种 | 大写；法币为 ISO 4217，稳定币为资产代码 | USD、SGD、USDT、USDC |
| 网络 | ethereum、tron、solana、base、polygon、arbitrum、bsc | solana |
| 时间 | Unix 秒整数 | 1718726400 |
| 比例 | 比例值统一使用字符串，不使用浮点数 | "0.9998" |
| 空字段 | 不适用的可选字段不返回 | — |

列表类接口统一采用游标分页：limit 默认 20、最大 100，响应返回 `next_cursor`，最后一页不返回该字段。账户查询类接口例外：账户列表一次返回全部账户，不支持分页与筛选。

创建类接口支持两种幂等方式：请求头 `Idempotency-Key`，以及请求体中的 `external_xxx_id`（与 `merchant_id` 共同构成幂等键，同一商户内唯一）。相同 Key 携带不同参数时返回 409 `idempotency_conflict`；网络超时重试请沿用同一幂等标识。

## 事件

事件记录商户名下资源的状态变化，由 StablePay 以 Webhook 推送到商户配置的地址。事件查询接口暂不对外提供，商户侧以推送内容与对账查询为准。

### 事件类型

| 事件 | 说明 |
| :- | :- |
| account.updated | 账户信息变更 |
| balance.updated | 账户可用余额或冻结余额变化 |
| deposit.completed | 稳定币充值到账，data 为充值记录 |
| withdrawal.processing / `payment_submitted` / completed / `bounced_back` | 提现生命周期 |
| `account_transfer.completed` | 账户划转完成 |

推送请求头携带 `X-StablePay-Event-Type` 与 `X-StablePay-Event-ID`；推送失败自动重试 10 次，指数退避从 2 分钟起、最长间隔 1024 分钟。同一事件可能重复送达，商户侧应以 `X-StablePay-Event-ID` 幂等去重，并以余额查询与对应记录核对最终状态。详见 Webhook 通知。

## 余额口径与数据一致性

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

余额类接口返回的 `as_of` 是本次查询的数据库观察时间，不是数据版本号，也不保证多次请求处于同一快照；两次请求之间余额变化属正常，以账本为准。转账状态为 completed 表示业务完成，不代表余额立即入账。写接口的幂等由 `Idempotency-Key` 与 `external_xxx_id` 保证。

## 错误响应与错误码

错误响应统一信封：error 对象（type、code、message、param）、`request_id` 与 timestamp。排查问题时请提供 `request_id`。

错误响应示例

```json theme={"system"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The amount must be greater than zero.",
    "param": "amount"
  },
  "request_id": "9000000099",
  "timestamp": 1718726400
}
```

| 状态码 | 错误码 | 说明 |
| :- | :- | :- |
| 400 | `invalid_parameter` | 参数缺失或取值不合法，如金额为 0、币种或网络不支持 |
| 401 | `invalid_api_key` | API Key 缺失、无效或已吊销，或签名校验失败 |
| 403 | `permission_denied` | 商户未授权该 App，或 App 无权访问目标商户 |
| 404 | `resource_not_found` | 资源不存在或不属于目标商户 |
| 409 | conflict | 业务状态冲突：`idempotency_conflict` 幂等键冲突、`insufficient_funds` 余额不足 |
| 429 | `rate_limit_exceeded` | 请求频率超限，退避后重试 |
| 500 | `internal_error` | 平台内部错误，凭 `request_id` 联系排查 |
| 503 | — | 余额查询服务暂时不可用，用新的 timestamp、nonce 与签名重试 |

error.type 取值：`api_error`、`invalid_request_error`、`authentication_error`、`permission_error`、`resource_not_found`、conflict、`rate_limit_error`。param 仅在能定位到具体参数时返回。重试时务必重新生成 timestamp 与 nonce；401 不要盲目重试。

## 按错误码处理

| 错误码 | 是否重试 | 建议处理 |
| :- | :- | :- |
| `invalid_parameter` | 否 | 按 param 定位参数并修正后重新提交；不要原样重试 |
| `invalid_api_key` | 否 | 检查 Key 是否有效、签名串是否少拼点号、服务端时间是否准确 |
| `permission_denied` | 否 | 服务商 App 检查 `merchant_id` 是否在已授权范围内 |
| `resource_not_found` | 否 | 核对资源 ID 与商户归属，确认资源未被删除 |
| `idempotency_conflict` | 否 | 同一幂等键换了参数：复用原参数，或换新的幂等键 |
| `insufficient_funds` | 否 | 余额不足：先查 `available_amount`，再调整金额或补充资金 |
| `rate_limit_exceeded` | 是 | 指数退避重试，并降低并发 |
| `internal_error` / 503 | 是 | 换新的 timestamp、nonce 与签名后退避重试，持续失败再附 `request_id` 排查 |

写接口重试时务必沿用同一个幂等键（`Idempotency-Key` 或 `external_xxx_id`），并重新生成 timestamp 与 nonce，避免把一次操作重复执行。

## 版本与变更记录

| 版本 | 变更 |
| :- | :- |
| 2026-09-29 | 首个公开版本：账户与余额查询、稳定币充值与提现、账户划转、收款人共 17 个接口；事件通过 Webhook 推送，不提供事件查询接口。 |

## 接口边界

* 账户开立、账户重命名与商户管理在商户后台完成，不通过本 API。
* 本 API 只返回当前商户自己的账户与交易数据，跨商户查询不可用。
* 跨商户资金调拨与平台账户收款由 Payouts 产品提供。
* 商户 KYB / KYC 资料提交与审核状态查询不通过本 API。

## 相关文档

* [全球账户产品文档](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.