Balance API

The Balance API lets you check your merchant account balances across all supported currencies. Use it to monitor available funds, track frozen amounts from pending payouts, and verify sufficient funds before initiating withdrawals.

Balances are returned per currency within a single balance object. Each currency tracks value (available) and value_freezing (frozen). The value_blocking and enabled fields are currently constant compatibility fields in the runtime response.

Retrieve Balances

Use the balance.get method to retrieve your current balances for all currencies. Endpoint: POST https://api.bafanglaicai88.com/public/api/multihub/v1

Request

BODY='{"method":"balance.get","params":{}}'
HASH=$(printf '%s%s' "$BODY" "YOUR_SECRET_KEY" | sha512sum | awk '{print $1}')
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -X POST "https://api.bafanglaicai88.com/public/api/multihub/v1" \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 42" \
  -H "X-Data-Hash: ${HASH}" \
  -H "X-Data-Timestamp: ${TIMESTAMP}" \
  -H "X-Data-Nonce: ${NONCE}" \
  --data-binary "${BODY}"

import hashlib
import requests
import json
import time
import uuid

SECRET_KEY = "your_secret_key"
APPLICATION_ID = "42"

body = {
    "method": "balance.get",
    "params": {}
}

body_json = json.dumps(body, separators=(",", ":"))
data_hash = hashlib.sha512((body_json + SECRET_KEY).encode()).hexdigest()

response = requests.post(
    "https://api.bafanglaicai88.com/public/api/multihub/v1",
    headers={
        "Content-Type": "application/json",
        "X-Data-Application-Id": APPLICATION_ID,
        "X-Data-Hash": data_hash,
        "X-Data-Timestamp": str(int(time.time())),
        "X-Data-Nonce": str(uuid.uuid4()),
    },
    data=body_json,
    timeout=(3.05, 30),
)

data = response.json()
print(data)

const crypto = require('crypto');
const fetch = require('node-fetch');

const SECRET_KEY = 'your_secret_key';
const APPLICATION_ID = '42';

const body = {
  method: 'balance.get',
  params: {},
};

const bodyJson = JSON.stringify(body);
const dataHash = crypto.createHash('sha512')
  .update(bodyJson + SECRET_KEY)
  .digest('hex');
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();

const response = await fetch('https://api.bafanglaicai88.com/public/api/multihub/v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Data-Application-Id': APPLICATION_ID,
    'X-Data-Hash': dataHash,
    'X-Data-Timestamp': timestamp,
    'X-Data-Nonce': nonce,
  },
  body: bodyJson,
  signal: AbortSignal.timeout(30000),
});

const data = await response.json();
console.log(data);

Response

Successful responses return HTTP 200. Error responses return HTTP 400. Always check the success field to determine if the request was processed correctly.

{
  "success": true,
  "result": {
    "balance": {
      "id": 0,
      "amounts": [
        {
          "value": 150000,
          "value_freezing": 25000,
          "value_blocking": 0,
          "currency": "INR",
          "enabled": true
        },
        {
          "value": 50000,
          "value_freezing": 0,
          "value_blocking": 0,
          "currency": "MXN",
          "enabled": true
        },
        {
          "value": 75000,
          "value_freezing": 0,
          "value_blocking": 0,
          "currency": "TRY",
          "enabled": true
        }
      ],
      "enabled": true
    }
  },
  "request_id": "req_abc123def456",
  "processing_time": 15
}

Error Response

If the request fails (e.g., invalid authentication), the response will contain an error field with HTTP 400:

{
  "success": false,
  "error": {
    "code": 3000,
    "message": "Authentication error",
    "details": null,
    "context": null
  },
  "request_id": "req_xyz789",
  "processing_time": 2
}

Response Fields

Envelope Fields

Field	Type	Description
`success`	boolean	Whether the request was processed successfully
`result`	object \| null	Response data (present when `success` is `true`)
`error`	object \| null	Error details (present when `success` is `false`)
`request_id`	string	Unique identifier for this request, useful for debugging
`processing_time`	integer	Server-side processing time in milliseconds

Balance Object

Field	Type	Description
`balance.id`	integer	Balance identifier. Returns the `service_id` if included in the request, otherwise `0`
`balance.enabled`	boolean	Currently always `true` in the runtime response
`balance.amounts`	array	Array of per-currency balance entries

Amount Entry Fields

Field	Type	Description
`value`	integer	Funds available for new withdrawals, in minor units
`value_freezing`	integer	Funds reserved by pending withdrawals, in minor units
`value_blocking`	integer	Currently always `0`, in minor units
`currency`	string	ISO 4217 currency code (e.g., `INR`, `MXN`)
`enabled`	boolean	Currently always `true` in the runtime response

All monetary values are returned as integers in minor units (e.g., paise for INR, centavos for MXN). For example, 150000 INR = 1,500.00 INR. Use integer or decimal arithmetic to avoid floating-point precision issues.

Balance values:

value — funds you can use right now for new withdrawals or payouts
value_freezing — funds reserved by pending withdrawals that have not yet completed. These are temporarily locked and cannot be used for new operations
value_blocking — currently a constant compatibility field with value 0

When a withdrawal completes, frozen funds are released and debited. If a withdrawal fails, frozen funds return to value.

Multi-Currency Support

The balance.get method returns balances for all currencies associated with your merchant account in a single balance.amounts array. There is no need to query each currency separately. If your merchant account is configured for multiple currencies (e.g., INR, MXN, TRY, ARS, AUD, LKR, UYU), you will see an entry for each one in the amounts array. Currencies with no activity will not appear in the response.

Usage Example: Check Balance Before Withdrawal

import hashlib
import requests
import json
import time
import uuid

SECRET_KEY = "your_secret_key"
APPLICATION_ID = "42"

body = {
    "method": "balance.get",
    "params": {}
}

body_json = json.dumps(body, separators=(",", ":"))
data_hash = hashlib.sha512((body_json + SECRET_KEY).encode()).hexdigest()

response = requests.post(
    "https://api.bafanglaicai88.com/public/api/multihub/v1",
    headers={
        "Content-Type": "application/json",
        "X-Data-Application-Id": APPLICATION_ID,
        "X-Data-Hash": data_hash,
        "X-Data-Timestamp": str(int(time.time())),
        "X-Data-Nonce": str(uuid.uuid4()),
    },
    data=body_json,
    timeout=(3.05, 30),
)

data = response.json()

if data["success"]:
    for amount in data["result"]["balance"]["amounts"]:
        if amount["currency"] == "INR":
            available = amount["value"]
            payout_amount = 50000  # 500.00 INR

            if available < payout_amount:
                print(f"Insufficient balance: {available} < {payout_amount}")
            else:
                print(f"Sufficient balance ({available}). Proceeding with withdrawal.")
                # Proceed with withdrawal
else:
    print(f"Error: {data['error']}")

const crypto = require('crypto');
const fetch = require('node-fetch');

const SECRET_KEY = 'your_secret_key';
const APPLICATION_ID = '42';

const body = {
  method: 'balance.get',
  params: {},
};

const bodyJson = JSON.stringify(body);
const dataHash = crypto.createHash('sha512')
  .update(bodyJson + SECRET_KEY)
  .digest('hex');
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();

const response = await fetch('https://api.bafanglaicai88.com/public/api/multihub/v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Data-Application-Id': APPLICATION_ID,
    'X-Data-Hash': dataHash,
    'X-Data-Timestamp': timestamp,
    'X-Data-Nonce': nonce,
  },
  body: bodyJson,
  signal: AbortSignal.timeout(30000),
});

const data = await response.json();

if (data.success) {
  const inrAmount = data.result.balance.amounts.find(a => a.currency === 'INR');
  if (inrAmount) {
    const payoutAmount = 50000; // 500.00 INR
    if (inrAmount.value < payoutAmount) {
      console.error(`Insufficient balance: ${inrAmount.value} < ${payoutAmount}`);
    } else {
      console.log(`Sufficient balance (${inrAmount.value}). Proceeding with withdrawal.`);
      // Proceed with withdrawal
    }
  }
} else {
  console.error('Error:', data.error);
}

How Balance Changes

Your balance updates automatically in response to payment lifecycle events:

Event	Effect on Balance
Deposit completed	`value` increases by net amount (deposit amount minus fee)
Withdrawal created	`value_freezing` increases, `value` decreases by the withdrawal amount
Withdrawal completed	`value_freezing` decreases (funds sent to recipient)
Withdrawal failed	`value_freezing` decreases, `value` increases (funds unfrozen)
Refund processed	`value` decreases by refund amount

Balance changes are reflected immediately after each event. You can poll balance.get to track updates in real time, or use webhooks to receive notifications when payment events occur.

Authentication

All API requests use the same authentication mechanism:

Header	Description
`X-Data-Application-Id`	Your application ID (integer)
`X-Data-Hash`	SHA-512 hash of the request body concatenated with your secret key
`X-Data-Timestamp`	Current Unix timestamp in seconds
`X-Data-Nonce`	Unique nonce for this request

The hash is computed as:

SHA512(requestBody + secretKey)

Where requestBody is the JSON string of the request body exactly as sent, and secretKey is your merchant secret key.

Getting Started

Guides

SDKs & Examples

Reference

Balance Guide

Balance API

Retrieve Balances

Request

Response

Error Response

Response Fields

Envelope Fields

Balance Object

Amount Entry Fields

Multi-Currency Support

Usage Example: Check Balance Before Withdrawal

How Balance Changes

Authentication

​Balance API

​Retrieve Balances

​Request

​Response

​Error Response

​Response Fields

​Envelope Fields

​Balance Object

​Amount Entry Fields

​Multi-Currency Support

​Usage Example: Check Balance Before Withdrawal

​How Balance Changes

​Authentication

Balance API

Retrieve Balances

Request

Response

Error Response

Response Fields

Envelope Fields

Balance Object

Amount Entry Fields

Multi-Currency Support

Usage Example: Check Balance Before Withdrawal

How Balance Changes

Authentication