上游余额查询 API
版本：v1.0 / 更新时间：2026-09-08 / 用途：商户在收银并提交上游履约前，查询当前服务链路可用的上游预充值余额。接口正式对外开放以平台发布通知为准。
接口入口
| 项目 | 说明 |
|---|---|
| 请求地址 | GET https://api.laifuagi.cn/openapi/v1/balance/upstream |
| Content-Type | 无请求体（GET） |
| 签名方式 | HMAC-SHA256，Base64 URL-safe，去除末尾 =；规则与 H5 产品统一入口一致，GET 无请求体时签名串最后一行（body）为空字符串。 |
| 能力边界 | 本接口只查询余额，不建单、不支付、不冻结、不触发上游履约。 |
请求头
| Header | 必填 | 说明 |
|---|---|---|
app_id | 是 | 开放平台应用 ID。 |
timestamp | 是 | 秒级时间戳。 |
nonce | 是 | 随机字符串，建议每次请求唯一。 |
sign | 是 | 按签名串计算得到的签名。 |
用途与说明
| 场景 | 说明 |
|---|---|
| 收银前预检 | 商户在收银或确认收款、提交上游履约前调用本接口，了解上游可用额度；上游余额为零或不足时，先不发起履约，避免“本地已收款、上游扣款失败”的体验问题。 |
| 余额口径 | 返回的是平台在上一级服务方的预充值可用余额（元）。余额按 下游 → 来福 → 上一级服务方 逐级查询，不返回商户本地账户余额（本地账户口径请以商户中心展示为准）。 |
| 非冻结 | 余额查询只是预检，不是冻结。并发订单仍可能在查询与实际受理之间消耗余额，最终结果以上游受理结果和订单通知为准。 |
响应字段
| 字段 | 说明 |
|---|---|
code | 业务状态码，200 表示查询成功。 |
msg | 业务提示。 |
data.availableBalance | 上游预充值可用余额，字符串，单位元（如 "4838.74"）。 |
data.currency | 金额币种，固定 CNY。 |
{"code":200,"msg":"操作成功","data":{"availableBalance":"4838.74","currency":"CNY"}}常见错误
| 提示 | 含义 |
|---|---|
| 签名错误或应用不存在 | 检查 app_id、密钥、签名串、时间戳和 nonce。 |
| 余额服务暂不可用 | 上一级余额服务查询失败或超时，请稍后重试；不要据此继续发起履约。 |