API 查询余额
大约 3 分钟
请求
余额查询API使商户能够检索实时账户余额信息。
请求路径：
沙盒：
https://sandbox-gateway.smilepayz.com/v2.0/inquiry-balance
生产：https://gateway.smilepayz.com/v2.0/inquiry-balance
请求头参数
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP内容类型规范 固定值：application/json 正确解析请求所必需 |
| X-TIMESTAMP | M | String | ISO 8601日期时间格式，带时区偏移 格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00 注意：必须是当前服务器时间，误差在±5分钟内 |
| X-SIGNATURE | M | String | 请求认证的数字签名。 参见签名生成 |
| X-PARTNER-ID | M | String | 平台分配的唯一商户标识符 格式：字母数字字符串 用于商户认证和交易路由 请输入merchantID |
请求体参数
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| accountNo | M | String(128) | 余额查询的商户账户标识符 格式：字母数字字符串 最大长度：128个字符 用于识别余额检索的特定账户 |
| balanceTypes | M | List(String) | 要检索的余额类型规范 格式：预定义余额类型代码数组 默认：["BALANCE"] 示例：BALANCE、AVAILABLE |
重要说明
1. 沙盒环境：
accountNo使用随机生成的字符串值用于测试目的
2. 生产环境：accountNo可以从商户后端系统检索。
参见如何获取生产账户号码
3. 收款账户： 用于从所有入账支付交易中收集资金
4. 付款账户： 用于处理付款和提款交易
5. 账户转账： 余额可以在不同账户类型之间转移。
参见账户转账指南
请求头示例 – 余额查询请求：
POST {Base URL}/v2.0/inquiry-balance HTTP/1.2
Content-type: application/json
X-TIMESTAMP: 2020-12-18T15:06:00+07:00
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 20001
{
"accountNo": "21020030202403071031",
"balanceTypes": [
"BALANCE"
]
}
响应
HTTP请求
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP响应内容类型规范 固定值：application/json 指示JSON响应格式 |
| X-TIMESTAMP | M | String | ISO 8601日期时间格式，带时区偏移 格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00 |
响应体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| code | M | String | API响应状态码，指示操作结果 格式：两位数字字符串 成功："00"，错误：其他代码 用于程序化响应处理 |
| message | M | String | 人类可读的响应状态描述 格式：UTF-8编码字符串 提供操作结果的详细信息 |
| accountInfos | M | BalanceAccounts | 账户余额信息容器 包含余额类型、金额和可用余额详情 参见余额账户模型 |
| accountNo | O | String | 用于参考的原始账户标识符 格式：与请求accountNo相同 用于账户验证和跟踪 |
| balanceTypes | O | List | 已处理的请求余额类型 格式：余额类型代码数组 包含成功检索的余额类型 |
| name | O | String | 用于显示的账户持有人姓名 格式：UTF-8编码字符串 在余额查询结果中显示 |
| additionalInfo | O | JsonString | 额外的账户信息和元数据 格式：JSON对象 包含可用的补充账户详情 |
响应体示例 – 余额查询响应：
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
{
"code": "00",
"message": "成功",
"accountNo": "21020030202403071031",
"name": "沙盒测试",
"balanceTypes": [
"balance"
],
"accountInfos": {
"balanceType": "BALANCE",
"amount": {
"currency": "IDR",
"value": "250000"
},
"availableBalance": {
"currency": "IDR",
"value": "250000"
}
}
}