余额查询接口文档
接口说明
请求URL：https://api.openpayhub.com/api/checkBalance
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded
认证方式：Header 认证（X-Api-Key + X-Api-Secret）
请求头参数
| 字段名 | 变量名 | 必填 | 类型 | 描述 |
|---|---|---|---|---|
| API密钥 | X-Api-Key | 是 | String | 商户API密钥，用于身份认证 |
| API密钥 | X-Api-Secret | 是 | String | 商户API密钥，用于身份认证（MD5加密后对比） |
请求参数
该接口无需请求体参数，认证信息通过请求头传递。
请求示例
curl --location 'https://api.openpayhub.com/api/checkBalance' \
--header 'X-Api-Key: your_api_key' \
--header 'X-Api-Secret: your_api_secret' \
--header 'Content-Type: application/json'返回参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | code | 是 | int | 0 | 0-处理成功，其他-处理有误 |
| 返回信息 | message | 否 | String | success | 具体返回信息 |
| 返回数据 | data | 否 | Object | {} | 返回数据对象 |
data数据格式
| 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| balance | 是 | float | 1000.00 | 商户余额 |
成功返回示例
{
"code": 0,
"message": "success",
"data": {
"balance": 1000.00
}
}错误返回示例
// API Key 无效
{
"code": 400,
"message": "X-Api-Key Is Invalid",
"data": ""
}
// API Key 未授权
{
"code": 401,
"message": "X-Api-Key Is unauthrized",
"data": ""
}
// API Secret 未授权
{
"code": 401,
"message": "X-Api-Secret Is unauthrized",
"data": ""
}
// 商户不存在
{
"code": 404,
"message": "Merchant Not Found",
"data": ""
}
// IP 不在白名单中
{
"code": 403,
"message": "Ip not allowed-192.168.1.1",
"data": ""
}错误码说明
| 错误码 | 说明 |
|---|---|
| 0 | 请求成功 |
| 400 | 请求参数错误（X-Api-Key 或 X-Api-Secret 为空） |
| 401 | 未授权（API Key 或 Secret 验证失败） |
| 403 | 禁止访问（IP 不在白名单中） |
| 404 | 商户不存在 |
注意事项
重要提示
- 调用接口前请确保已在后台配置 IP 白名单
- X-Api-Secret 需要进行 MD5 加密后与数据库中的 iv 字段对比
- 建议在生产环境使用 HTTPS 协议
- 接口会记录请求日志，包含请求 IP 和 API Key
业务流程说明
- 验证请求头中 X-Api-Key 和 X-Api-Secret 是否为空
- 获取客户端真实 IP 地址
- 记录请求日志
- 根据 X-Api-Key 查询商户密钥信息
- 验证 X-Api-Secret（MD5 加密后对比）
- 查询商户信息并验证 IP 白名单
- 查询商户余额并返回