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.
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

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_sk_your_key"
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" \
  -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

ParameterRequiredDefaultDescription
currencyNoMXNISO 4217 currency code (ARS, AUD, LKR, MXN, TRY, 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_sk_your_key"
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": [
    {
      "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.

​
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",
  {
    headers: { "X-API-Key": "qp_test_sk_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