API 余额查询

请求

余额查询 API 使商户能够获取其 Smilepayz 账户的实时余额信息。此 API 提供不同账户类型的详细余额信息，包括收款账户和付款账户。

请求路径：

沙盒环境：https://sandbox-gateway.smilepayz.com/v2.0/inquiry-balance
生产环境：https://gateway.smilepayz.com/v2.0/inquiry-balance

请求头参数

字段	必填	类型	描述
Content-Type	是	String	HTTP 内容类型规范固定值：application/json 用于正确解析请求
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00 注意：必须是当前服务器时间，误差在 ±5 分钟内
X-SIGNATURE	是	String	请求认证的数字签名参见签名生成
X-PARTNER-ID	是	String	平台分配的唯一商户标识符格式：字母数字字符串用于商户认证和交易路由请输入 merchantID

请求体参数

字段	必填	类型	描述
accountNo	是	String(128)	余额查询的商户账户标识符格式：字母数字字符串最大长度：128 个字符用于识别余额查询的特定账户
balanceTypes	是	List(String)	要检索的余额类型规范格式：预定义余额类型代码数组默认值：["BALANCE"] 示例：BALANCE, AVAILABLE 用于指定要查询的余额类型

重要说明

1. 沙盒环境： accountNo 使用随机生成的字符串值用于测试目的
2. 生产环境： accountNo 可以从商户后端系统获取。
参见如何获取生产环境账户号
3. 收款账户： 用于收集所有入账交易中的资金
4. 付款账户： 用于处理付款和提现交易
5. 账户转账： 余额可以在不同账户类型之间转移。
参见账户转账指南

请求体示例 – 余额查询请求：

Content-type: application/json
X-TIMESTAMP: 2020-12-18T15:06:00-05:00
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 20001

{
  "accountNo": "21220030202403071031",
  "balanceTypes": [
    "BALANCE"
  ]
}

响应

HTTP 响应

字段	必填	类型	描述
Content-Type	是	String	HTTP 响应内容类型规范固定值：application/json 表示 JSON 响应格式
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00

响应体参数

字段	必填	类型	描述
code	是	String	API 响应状态码，表示操作结果格式：两位数字字符串成功："00"，错误：其他代码用于程序化响应处理
message	是	String	人类可读的响应状态描述格式：UTF-8 编码字符串提供操作结果的详细信息根据请求语言进行本地化
accountNo	否	String	余额查询的商户账户标识符格式：字母数字字符串与请求中提供的 accountNo 相同用于账户识别和验证
name	否	String	账户持有人姓名或账户描述格式：UTF-8 编码字符串账户的显示名称用于账户识别和显示目的
balanceTypes	否	Array	请求的余额类型规范格式：预定义余额类型代码数组示例：["BALANCE"], ["AVAILABLE"] 表示查询了哪些余额类型
accountInfos	是	Object	详细余额信息容器包含指定账户的综合余额详情参见余额账户模型
balanceType	是	String	报告的余额类型格式：预定义余额类型代码示例：BALANCE, AVAILABLE 表示特定的余额类别
amount	是	Object	账户总余额金额包含货币和价值信息参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：PEN（秘鲁索尔）确定余额金额的货币单位
value	是	String	余额金额的字符串值格式：数值的字符串表示示例："250000" 表示 PEN 250000 用于精确的余额表示
availableBalance	是	Object	可用于交易的余额包含货币和价值信息可能因冻结或限制而与总余额不同参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：PEN（秘鲁索尔）确定可用余额的货币单位
value	是	String	可用余额金额的字符串值格式：数值的字符串表示示例："250000" 表示 PEN 250000 用于精确的可用余额表示
additionalInfo	否	Object	额外的账户信息和元数据格式：JSON 对象在可用时包含补充的账户详情用于扩展的账户信息

Content-type: application/json 
X-TIMESTAMP: 2020-12-17T10:55:00-05:00

{
  "code": "00",
  "message": "成功",
  "accountNo": "21220030202403071031",
  "name": "沙盒测试",
  "balanceTypes": [
    "BALANCE"
  ],
  "accountInfos": {
    "balanceType": "BALANCE",
    "amount": {
      "currency": "PEN",
      "value": "250000"
    },
    "availableBalance": {
      "currency": "PEN",
      "value": "250000"
    }
  }
}

API 余额查询

# 请求

# 请求路径：

# 请求头参数

# 请求体参数

# 请求体示例 – 余额查询请求：

# 响应

# HTTP 响应

# 响应体参数

请求

请求路径：

请求头参数

请求体参数

请求体示例 – 余额查询请求：

响应

HTTP 响应

响应体参数