Balance API

Use the Balance API to check your merchant account balance. This is especially important before initiating withdrawals to ensure sufficient funds.

API v1 Balance requests require the balance.read or balance.view scope on your API key. API v2 merchants use HMAC authentication with the same balance permissions.

Get Balance by Currency

Pass balance_type=main explicitly when checking funds for a payout. Omitting the type does not guarantee selection of the main balance. Retrieve the balance for a specific currency.

curl -X GET "https://api.lux-core.io/api/v1/balance?currency=ARS&balance_type=main" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret"

API v2 merchants use the same response format through the HMAC-authenticated endpoint:

curl -X GET "https://api.lux-core.io/api/v2/balance?currency=ARS&balance_type=main" \
  -H "X-Merchant-Id: 123" \
  -H "X-Timestamp: <unix_timestamp_seconds>" \
  -H "X-Nonce: <unique_nonce>" \
  -H "X-Signature-Version: v1" \
  -H "X-Signature: hmac_sha256=<signature>"

Query Parameters

Parameter	Required	Default	Description
`currency`	No	Merchant default	Enabled ISO 4217 currency code; pass it explicitly for reconciliation
`balance_type`	No	No selector	Balance type: `main`, `deposit`, `withdrawal`, `commission`, `frozen`

Response

{
  "success": true,
  "merchant_id": 123,
  "currency": "ARS",
  "balance_type": "main",
  "balance_amount": 1500000,
  "available_amount": 1200000,
  "frozen_amount": 300000,
  "new_balance": 1500000,
  "available_balance": 1200000,
  "balance": {
    "currencyCode": "ARS",
    "balanceType": "main",
    "balanceAmount": "1500000",
    "availableAmount": "1200000",
    "frozenAmount": "300000"
  }
}

Get All Balances

Retrieve balances for all currencies at once.

curl -X GET "https://api.lux-core.io/api/v1/balance/all" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret"

API v2 merchants can request all balances with HMAC authentication:

curl -X GET "https://api.lux-core.io/api/v2/balance/all" \
  -H "X-Merchant-Id: 123" \
  -H "X-Timestamp: <unix_timestamp_seconds>" \
  -H "X-Nonce: <unique_nonce>" \
  -H "X-Signature-Version: v1" \
  -H "X-Signature: hmac_sha256=<signature>"

Response

{
  "success": true,
  "merchant_id": 123,
  "balances": [
    {
      "merchantId": 123,
      "currencyId": 1,
      "currencyCode": "ARS",
      "balanceType": "main",
      "balanceAmount": "1500000",
      "availableAmount": "1200000",
      "frozenAmount": "300000",
      "new_balance": 1500000,
      "available_balance": 1200000
    }
  ],
  "total_balances": 1
}

Response Fields

Field	Type	Description
`balance_type`	string	Balance type: `main`, `deposit`, `withdrawal`, `commission`, or `frozen`
`balance_amount`	number	Total balance amount in minor units (centavos)
`available_amount`	number	Amount available for withdrawals, in minor units (centavos)
`frozen_amount`	number	Amount frozen by pending withdrawals, in minor units
`new_balance`	integer	Total balance as integer (same value as `balance_amount`)
`available_balance`	integer	Available balance as integer (same value as `available_amount`)

All amounts are in minor units. /balance top-level monetary fields are JSON numbers; nested balance.balanceAmount, balance.availableAmount and balance.frozenAmount are decimal strings. /balance/all uses the camelCase string fields shown above, plus numeric aliases. Prefer the string fields for exact arithmetic and validate numeric values before calculations.

API v2 HMAC Signing

For GET balance requests, sign an empty raw body. The empty body SHA-256 hash is:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Canonical string examples:

v1.<timestamp>.<nonce>.GET./api/v2/balance?currency=ARS&balance_type=main.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
v1.<timestamp>.<nonce>.GET./api/v2/balance/all.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

See Authentication for the complete HMAC header and signing rules.

Available vs Frozen:

available_amount — funds you can use right now for new withdrawals
frozen_amount — funds reserved by pending withdrawals that have not yet completed. These are temporarily locked and cannot be used for new operations

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

Usage Example: Check Balance Before Withdrawal

const balance = await fetch(
  "https://api.lux-core.io/api/v1/balance?currency=ARS&balance_type=main",
  {
    headers: { "X-API-Key": "qp_test_sk_your_key_id:your_secret" },
  },
).then((r) => r.json());

const availableMinor = BigInt(balance.balance.availableAmount);
const payoutAmountMinor = 250000n; // 2,500.00 ARS

if (availableMinor < payoutAmountMinor) {
  console.error(
    `Insufficient balance: ${availableMinor} < ${payoutAmountMinor}`,
  );
} else {
  // Proceed with withdrawal
}

import requests

balance = requests.get(
    "https://api.lux-core.io/api/v1/balance",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    params={"currency": "ARS", "balance_type": "main"}
).json()

available = int(balance["balance"]["availableAmount"])
payout_amount = 250000  # 2,500.00 ARS

if available < payout_amount:
    print(f"Insufficient balance: {available} < {payout_amount}")
else:
    # Proceed with withdrawal
    pass

How Balance Changes

Event	Effect
Deposit completed	`available_amount` increases by `net_amount` (deposit amount minus fee)
Withdrawal created	`frozen_amount` increases, `available_amount` decreases by the same amount
Withdrawal completed	`frozen_amount` decreases (funds sent to recipient)
Withdrawal failed	`frozen_amount` decreases, `available_amount` increases (funds unfrozen)
Refund processed	`available_amount` decreases by refund amount

Getting Started

Guides

SDKs & Examples

Reference

Balance Guide

Balance API

Get Balance by Currency

Query Parameters

Response

Get All Balances

Response

Response Fields

API v2 HMAC Signing

Usage Example: Check Balance Before Withdrawal

How Balance Changes

​Balance API

​Get Balance by Currency

​Query Parameters

​Response

​Get All Balances

​Response

​Response Fields

​API v2 HMAC Signing

​Usage Example: Check Balance Before Withdrawal

​How Balance Changes

Balance API

Get Balance by Currency

Query Parameters

Response

Get All Balances

Response

Response Fields

API v2 HMAC Signing

Usage Example: Check Balance Before Withdrawal

How Balance Changes