https://api.stablepay.co · 前缀：/api/v1 · HTTPS / JSON / UTF-8
概述与能力范围
全球账户 API 管理商户的多币种账户与账户级资金进出：查询账户与余额、稳定币充值与提现、同商户账户间划转、收款人管理，以及这些资源的事件推送（Webhook）。所有接口以 /api/v1 为前缀，商户身份由凭证确定：商户 App 不需要传merchant_id，服务商 App 通过 merchant_id 指定作用商户。
账户查询接口使用 8 位数字账户编号，列表以 object 与 data 返回；其余接口的业务资源 ID 为 10 位数字。所有涉及账户的参数统一使用 8 位
account_no。
认证与签名
所有请求携带 API Key 与签名三件套，规则与 StablePay 公共认证规范一致。
签名串为
{timestamp}.{nonce}.{requestBody}。GET 与 DELETE 没有请求体，{requestBody} 取空字符串，签名串以点号结尾；POST 与 PUT 使用实际发送的原始 JSON 字符串，计算签名后不要再重排字段或格式化。完整算法与多语言示例见 集成前准备。
凭证属于 App：商户 App 对应单一商户，请求不带 merchant_id；服务商 App 经商户授权后可服务多个商户，可在账户与余额查询、资金与收款人接口的 Query 或 Body 中传 merchant_id 指定作用商户。未授权或无权访问目标商户时返回 403 permission_denied。签名密钥只保存在服务端，重试时必须重新生成 timestamp 与 nonce。
数据约定
列表类接口统一采用游标分页：limit 默认 20、最大 100，响应返回
next_cursor，最后一页不返回该字段。账户查询类接口例外：账户列表一次返回全部账户，不支持分页与筛选。
创建类接口支持两种幂等方式：请求头 Idempotency-Key，以及请求体中的 external_xxx_id（与 merchant_id 共同构成幂等键，同一商户内唯一）。相同 Key 携带不同参数时返回 409 idempotency_conflict；网络超时重试请沿用同一幂等标识。
事件
事件记录商户名下资源的状态变化，由 StablePay 以 Webhook 推送到商户配置的地址。事件查询接口暂不对外提供，商户侧以推送内容与对账查询为准。事件类型
推送请求头携带
X-StablePay-Event-Type 与 X-StablePay-Event-ID；推送失败自动重试 10 次，指数退避从 2 分钟起、最长间隔 1024 分钟。同一事件可能重复送达，商户侧应以 X-StablePay-Event-ID 幂等去重，并以余额查询与对应记录核对最终状态。详见 Webhook 通知。
余额口径与数据一致性
余额类接口返回的
as_of 是本次查询的数据库观察时间，不是数据版本号，也不保证多次请求处于同一快照；两次请求之间余额变化属正常，以账本为准。转账状态为 completed 表示业务完成，不代表余额立即入账。写接口的幂等由 Idempotency-Key 与 external_xxx_id 保证。
错误响应与错误码
错误响应统一信封：error 对象（type、code、message、param）、request_id 与 timestamp。排查问题时请提供 request_id。
错误响应示例
error.type 取值：
api_error、invalid_request_error、authentication_error、permission_error、resource_not_found、conflict、rate_limit_error。param 仅在能定位到具体参数时返回。重试时务必重新生成 timestamp 与 nonce；401 不要盲目重试。
按错误码处理
写接口重试时务必沿用同一个幂等键（
Idempotency-Key 或 external_xxx_id），并重新生成 timestamp 与 nonce，避免把一次操作重复执行。
版本与变更记录
接口边界
- 账户开立、账户重命名与商户管理在商户后台完成，不通过本 API。
- 本 API 只返回当前商户自己的账户与交易数据，跨商户查询不可用。
- 跨商户资金调拨与平台账户收款由 Payouts 产品提供。
- 商户 KYB / KYC 资料提交与审核状态查询不通过本 API。