余额查询

请求

余额查询API使商户能够检索其账户的实时余额信息。此API提供详细的余额信息，包括可用余额、冻结金额和待结算金额。

请求路径

模板（未列国家请按运营提供的域名与编码拼接）

沙箱：https://{对应国家域名}/sandbox/{对应国家编码}/balance/v1
生产：https://{对应国家域名}/{对应国家编码}/balance/v1

推荐 Host 使用统一域名 openapi.toppayment.com；原国别域名仍可用。

按国家区分的完整地址

国家/地区	国家码	货币代码	沙箱	生产
菲律宾	ph	PHP	https://openapi.toppayment.com/sandbox/ph/balance/v1	https://openapi.toppayment.com/ph/balance/v1
印度尼西亚	id	IDR	https://openapi.toppayment.com/sandbox/id/balance/v1	https://openapi.toppayment.com/id/balance/v1
尼日利亚	ng	NGN	https://openapi.toppayment.com/sandbox/ng/balance/v1	https://openapi.toppayment.com/ng/balance/v1
印度	in	INR	https://openapi.toppayment.com/sandbox/in/balance/v1	https://openapi.toppayment.com/in/balance/v1
泰国	th	THB	https://openapi.toppayment.com/sandbox/th/balance/v1	https://openapi.toppayment.com/th/balance/v1
越南	vn	VND	https://openapi.toppayment.com/sandbox/vn/balance/v1	https://openapi.toppayment.com/vn/balance/v1
秘鲁	pe	PEN	https://openapi.toppayment.com/sandbox/pe/balance/v1	https://openapi.toppayment.com/pe/balance/v1
巴西	br	BRL	https://openapi.toppayment.com/sandbox/br/balance/v1	https://openapi.toppayment.com/br/balance/v1
墨西哥	mx	MXN	https://openapi.toppayment.com/sandbox/mx/balance/v1	https://openapi.toppayment.com/mx/balance/v1
哥伦比亚	co	COP	https://openapi.toppayment.com/sandbox/co/balance/v1	https://openapi.toppayment.com/co/balance/v1
玻利维亚	bo	BOB	https://openapi.toppayment.com/sandbox/bo/balance/v1	https://openapi.toppayment.com/bo/balance/v1
巴基斯坦	pk	PKR	https://openapi.toppayment.com/sandbox/pk/balance/v1	https://openapi.toppayment.com/pk/balance/v1
孟加拉	bd	BDT	https://openapi.toppayment.com/sandbox/bd/balance/v1	https://openapi.toppayment.com/bd/balance/v1

各国家 currency 与支付方式、银行编码说明见 地区支付说明。

地区支付说明

国家/地区	文档
菲律宾	地区支付说明 — 菲律宾
印度尼西亚	地区支付说明 — 印尼
尼日利亚	地区支付说明 — 尼日利亚
印度	地区支付说明 — 印度
泰国	地区支付说明 — 泰国
越南	地区支付说明 — 越南
秘鲁	地区支付说明 — 秘鲁
巴西	地区支付说明 — 巴西
墨西哥	地区支付说明 — 墨西哥
哥伦比亚	地区支付说明 — 哥伦比亚
玻利维亚	地区支付说明 — 玻利维亚
巴基斯坦	地区支付说明 — 巴基斯坦
孟加拉	地区支付说明 — 孟加拉

请求头参数

字段	必填	类型	描述
Content-Type	M	String	HTTP内容类型规范 固定值：application/json 正确解析请求所必需

请求体参数

字段	必填	类型	描述
currency	M	String(32)	货币代码 ISO 4217货币代码规范 示例：PHP、IDR、PKR（巴基斯坦）
mchNo	M	String(32)	商户编号 平台分配的唯一商户标识符 用于商户认证和交易路由
sign	M	String	签名 请求认证的数字签名 参见签名生成
timestamp	M	Number(13位数字)	时间戳 请求时间戳（毫秒级） 示例：1749102949784

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

Content-type: application/json

{
    "currency": "PHP",
    "mchNo": "{{mchNo}}",
    "sign": "按签名规则生成后替换",
    "timestamp": 1749102949784
}

响应

HTTP响应

字段	必填	类型	描述
Content-Type	M	String	HTTP响应内容类型规范 固定值：application/json 指示JSON响应格式

响应体参数

字段	必填	类型	描述
success	M	Boolean	请求是否成功 true：成功，false：失败
code	M	String	响应状态码 9999：成功 其他：失败
msg	O	String	响应消息 可读的响应状态描述 成功时为null
timeStamp	M	Number	响应时间戳 服务器响应时间（毫秒级）
data	M	Object	响应数据对象 包含余额详细信息
mchNo	M	String	商户编号 平台分配的唯一商户标识符
currency	M	String	货币代码 ISO 4217货币代码规范 示例：PHP、IDR、INR
totalAmount	M	Number	总金额 账户总金额（包含所有资金）
balance	M	Number	可用余额 当前可用于交易的余额
freeze	M	Number	冻结金额 当前被冻结无法使用的金额
waitingSettleAmount	M	Number	待结算金额 等待结算的金额
freezeWaitingSettleAmount	M	Number	冻结待结算金额 被冻结的待结算金额

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "mchNo": "G1",
        "currency": "IDR",
        "totalAmount": 1875716820.00000000,
        "balance": 1875689559.48000000,
        "freeze": 26149.52000000,
        "waitingSettleAmount": 980.00000000,
        "freezeWaitingSettleAmount": 131.00000000
    }
}