Skip to main content

​
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 three values independently: value (available), value_freezing (frozen), and value_blocking (blocked).

​
Retrieve Balances

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

​
Request

curl -X POST "https://api.123hub.pro/public/api/multihub/v1" \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 14701" \
  -H "X-Data-Hash: $(echo -n '{"method":"balance.get","params":{}}YOUR_SECRET_KEY' | sha512sum | awk '{print $1}')" \
  -d '{
    "method": "balance.get",
    "params": {}
  }'

​
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": 14701,
      "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
        }
      ],
      "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

FieldTypeDescription
successbooleanWhether the request was processed successfully
resultobject | nullResponse data (present when success is true)
errorobject | nullError details (present when success is false)
request_idstringUnique identifier for this request, useful for debugging
processing_timeintegerServer-side processing time in milliseconds

​
Balance Object

FieldTypeDescription
balance.idintegerBalance identifier (matches service_id from request)
balance.enabledbooleanWhether the balance account is enabled
balance.amountsarrayArray of per-currency balance entries

​
Amount Entry Fields

FieldTypeDescription
valueintegerFunds available for new withdrawals, in minor units
value_freezingintegerFunds reserved by pending withdrawals, in minor units
value_blockingintegerFunds blocked by the system, in minor units
currencystringISO 4217 currency code (e.g., INR, MXN)
enabledbooleanWhether this currency is enabled
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 — funds blocked by the system (e.g., holds or reserves)
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 and MXN), 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

SECRET_KEY = "your_secret_key"
APPLICATION_ID = "14701"

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.123hub.pro/public/api/multihub/v1",
    headers={
        "Content-Type": "application/json",
        "X-Data-Application-Id": APPLICATION_ID,
        "X-Data-Hash": data_hash,
    },
    json=body,
)

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']}")

​
How Balance Changes

Your balance updates automatically in response to payment lifecycle events:
EventEffect on Balance
Deposit completedavailable increases by net amount (deposit amount minus fee)
Withdrawal createdfrozen increases, available decreases by the withdrawal amount
Withdrawal completedfrozen decreases (funds sent to recipient)
Withdrawal failedfrozen decreases, available increases (funds unfrozen)
Refund processedavailable 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 requests to the multihub API use the same authentication mechanism:
HeaderDescription
X-Data-Application-IdYour application ID (integer)
X-Data-HashSHA-512 hash of the request body concatenated with your secret key
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.