Balance Inquiry

Request

The Balance Inquiry API enables merchants to retrieve real-time balance information for their accounts. This API provides detailed balance information, including available balance, frozen amount, and pending settlement amount.

Request URL

Template (if your country is not listed, use the domain and code provided by your account manager)

Sandbox: https://{country domain}/sandbox/{countryCode}/balance/v1
Production: https://{country domain}/{countryCode}/balance/v1

Prefer Host openapi.toppayment.com; legacy country domains remain available.

Full URLs by country

Country / region	Code	Example currency	Sandbox	Production
Philippines	ph	PHP	https://openapi.toppayment.com/sandbox/ph/balance/v1	https://openapi.toppayment.com/ph/balance/v1
Indonesia	id	IDR	https://openapi.toppayment.com/sandbox/id/balance/v1	https://openapi.toppayment.com/id/balance/v1
Nigeria	ng	NGN	https://openapi.toppayment.com/sandbox/ng/balance/v1	https://openapi.toppayment.com/ng/balance/v1
India	in	INR	https://openapi.toppayment.com/sandbox/in/balance/v1	https://openapi.toppayment.com/in/balance/v1
Thailand	th	THB	https://openapi.toppayment.com/sandbox/th/balance/v1	https://openapi.toppayment.com/th/balance/v1
Vietnam	vn	VND	https://openapi.toppayment.com/sandbox/vn/balance/v1	https://openapi.toppayment.com/vn/balance/v1
Peru	pe	PEN	https://openapi.toppayment.com/sandbox/pe/balance/v1	https://openapi.toppayment.com/pe/balance/v1
Brazil	br	BRL	https://openapi.toppayment.com/sandbox/br/balance/v1	https://openapi.toppayment.com/br/balance/v1
Mexico	mx	MXN	https://openapi.toppayment.com/sandbox/mx/balance/v1	https://openapi.toppayment.com/mx/balance/v1
Colombia	co	COP	https://openapi.toppayment.com/sandbox/co/balance/v1	https://openapi.toppayment.com/co/balance/v1
Bolivia	bo	BOB	https://openapi.toppayment.com/sandbox/bo/balance/v1	https://openapi.toppayment.com/bo/balance/v1
Pakistan	pk	PKR	https://openapi.toppayment.com/sandbox/pk/balance/v1	https://openapi.toppayment.com/pk/balance/v1
Bangladesh	bd	BDT	https://openapi.toppayment.com/sandbox/bd/balance/v1	https://openapi.toppayment.com/bd/balance/v1

See Regional payment guides for currency and payment method details.

Regional payment guides

Country / region	Guide
Philippines	Philippines — payment guide
Indonesia	Indonesia — payment guide
Nigeria	Nigeria — payment guide
India	India — payment guide
Thailand	Thailand — payment guide
Vietnam	Vietnam — payment guide
Peru	Peru — payment guide
Brazil	Brazil — payment guide
Mexico	Mexico — payment guide
Colombia	Colombia — payment guide
Bolivia	Bolivia — payment guide
Pakistan	Pakistan — payment guide
Bangladesh	Bangladesh — payment guide

Request Header Parameters

Field	Required	Type	Description
Content-Type	M	String	HTTP content type specification Fixed value: application/json Required for proper request parsing

Request Body Parameters

Field	Required	Type	Description
currency	M	String(32)	Currency code ISO 4217 Example: PHP, IDR, PKR (Pakistan)
mchNo	M	String(32)	Merchant number Unique merchant identifier assigned by the platform Used for merchant authentication and transaction routing
sign	M	String	Signature Digital signature for request authentication See Signature Generation
timestamp	M	Number (13 digits)	Timestamp Request timestamp in milliseconds Example: 1749102949784

Request Body Example —Balance Inquiry Request:

Content-type: application/json

{
    "currency": "PHP",
    "mchNo": "{{mchNo}}",
    "sign": "Generate per signature rules and replace",
    "timestamp": 1749102949784
}

Response

HTTP Response

Field	Required	Type	Description
Content-Type	M	String	HTTP response content type specification Fixed value: application/json Indicates JSON response format

Response Body Parameters

Field	Required	Type	Description
success	M	Boolean	Request Success Status true: Success, false: Failure
code	M	String	Response Status Code 9999: Success Other: Failure
msg	O	String	Response Message Human-readable response status description Null on success
timeStamp	M	Number	Response Timestamp Server response time in milliseconds
data	M	Object	Response Data Object Contains balance details
mchNo	M	String	Merchant Number Unique merchant identifier assigned by the platform
currency	M	String	Currency Code ISO 4217 currency code specification Example: PHP, IDR, INR
totalAmount	M	Number	Total Amount Total account amount (including all funds)
balance	M	Number	Available Balance Current balance available for transactions
freeze	M	Number	Frozen Amount Amount currently frozen and unavailable for use
waitingSettleAmount	M	Number	Pending Settlement Amount Amount awaiting settlement
freezeWaitingSettleAmount	M	Number	Frozen Pending Settlement Amount Frozen amount awaiting settlement

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
    }
}