Wallet Balance

This endpoint returns current wallet balances for the given merchant PID. It requires HMAC signature verification and X-Api-Key.

Endpoint

POST {baseURL}/api/v2/wallet_balance.php
Content-Type: application/json; charset=utf-8

Authorization

All API requests must include the X-Api-Key header. API Key verification is mandatory for every request and cannot be bypassed. Requests without a valid key will be rejected with 401 Unauthorized .

Request must be authenticated by including a signature parameter in the JSON body.

The logic for creating this signature is identical for all V2 endpoints. Please follow the detailed instructions on our central guide:

➡️ V2 API Signature Generation

Required Headers

Header	Description	Required
Content-Type	Must be application/json; charset=utf-8	Yes
X-Api-Key	Must be included in every request	Yes

Security Note

Always generate HMAC signatures server-side. Never expose your secret key in client-side code.

Request Body

Parameter	Type	Description	Required
pid	string	Merchant Partner ID	Yes
signature	string	HMAC signature Signature Generation	Yes

{
 "pid": "your_merchant_pid",
 "signature": "generated_hmac_signature"
}

Response

Successful response contains user_balance (integers in smallest currency unit).

Success Response

{
 "status": "success",
 "message": "Balance fetched successfully",
 "user_balance": {
 "pid": "your_merchant_pid",
 "payin_balance": 25000,
 "payout_balance": 18500,
 "payin_matured_balance": 22000
 }
}

Response Fields

Field	Type	Description
status	string	"success" or "error"
message	string	Description message
user_balance.pid	string	Merchant PID
user_balance.payin_balance	integer	Payin wallet (smallest unit)
user_balance.payout_balance	integer	Payout wallet (smallest unit)
user_balance.payin_matured_balance	integer	Payin withdrawable/matured wallet (smallest unit)

Balance Types

Payin = funds received; Payout = funds available to pay out; Payin matured = withdrawable after settlement.

Error Responses

Common error responses and HTTP status codes.

HTTP Status	Error Message	Description
400	pid not provided	Required 'pid' missing
400	signature not provided	Required 'signature ' missing
401	Invalid signature	Signature verification failed
400	Invalid PID	PID not found in system
403	IP not allowed: [IP]	IP not whitelisted
401	X-Api-Key header is required	Returned when the X-Api-Key passed in header is missing or invalid
401	Invalid API key	API key mismatch
429	Rate limit exceeded	Too many requests (rate-limited)

Examples

Quick example requests to test the API.

cURL

curl -X POST "{baseURL}/api/v2/wallet_balance.php" \
 -H "Content-Type: application/json; charset=utf-8" \
 -H "X-Api-Key: YOUR_API_KEY" \
 -d '{"pid":"your_pid","signature":"generated_signature"}'

PHP cURL