Skip to main content

​
Balance API

Use the Balance API to check your merchant account balance. This is especially important before initiating withdrawals to ensure sufficient funds.
The Balance API requires the balance.read or balance.view scope on your API key.

​
Get Balance by Currency

Retrieve the balance for a specific currency. 
curl -X GET "https://api.lux-core.io/api/v1/balance?currency=ARS" \
  -H "X-API-Key: qp_test_your_key"

​
Query Parameters

ParameterRequiredDefaultDescription
currencyNoMXNISO 4217 currency code (ARS, MXN, UYU)
balance_typeNomainBalance 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
}

​
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_your_key"

​
Response

{
  "success": true,
  "merchant_id": 123,
  "balances": [
    {
      "currency": "ARS",
      "balance_type": "main",
      "balance_amount": "1500000",
      "available_amount": "1200000",
      "frozen_amount": "300000"
    },
    {
      "currency": "MXN",
      "balance_type": "main",
      "balance_amount": "850000",
      "available_amount": "850000",
      "frozen_amount": "0"
    }
  ],
  "total_balances": 2
}

​
Response Fields

FieldTypeDescription
balance_typestringBalance type: main, deposit, withdrawal, commission, or frozen
balance_amountstringTotal balance amount in minor units (centavos)
available_amountstringAmount available for withdrawals, in minor units (centavos)
frozen_amountstringAmount frozen by pending withdrawals, in minor units
new_balanceintegerTotal balance as integer (same value as balance_amount)
available_balanceintegerAvailable balance as integer (same value as available_amount)
All monetary values are returned as strings in minor units (centavos). For example, "1200000" = 12,000.00 ARS. Use integer or decimal arithmetic to avoid floating-point precision issues.
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', {
  headers: { 'X-API-Key': 'qp_test_your_key' }
}).then(r => r.json());

const availableMinor = parseInt(balance.available_amount, 10);
const payoutAmountMinor = 250000; // 2,500.00 ARS

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

​
How Balance Changes

EventEffect
Deposit completedavailable_amount increases by net_amount (deposit amount minus fee)
Withdrawal createdfrozen_amount increases, available_amount decreases by the same amount
Withdrawal completedfrozen_amount decreases (funds sent to recipient)
Withdrawal failedfrozen_amount decreases, available_amount increases (funds unfrozen)
Refund processedavailable_amount decreases by refund amount