Balance

Balance query

In this section, you will learn how to query balances for your PixToPay account, including current balances and history.

Available endpoint

  • Production: https://api.pixtopay.com.br/v2/balance

⚠️ Note: This endpoint is available in production only.

Query current balances

Query the current balances for your account, broken down by type and bank.

Route

GET /v2/balance

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Request example:

curl --location 'https://api.pixtopay.com.br/v2/balance' \
--header 'Authorization: API_KEY'

Response 200 - Success:

{
  "transactional": {
    "balance": 2222222.21,
    "balances": [
      {
        "bank": "STARKBANK",
        "amount": 1234567.89
      },
      {
        "bank": "GENIAL",
        "amount": 0
      },
      {
        "bank": "EFIPAY",
        "amount": 987654.32
      }
    ]
  },
  "operational": {
    "balance": 2222222.21,
    "balances": [
      {
        "bank": "STARKBANK",
        "amount": 1234567.89
      },
      {
        "bank": "GENIAL",
        "amount": 0
      },
      {
        "bank": "EFIPAY",
        "amount": 987654.32
      }
    ]
  }
}

Response Fields

ParameterTypeDescription
transactionalobjectTransactional balance (available for transactions)
transactional.balancenumberTotal transactional balance in BRL
transactional.balancesarrayBreakdown by bank
transactional.balances[].bankstringBank name
transactional.balances[].amountnumberBalance at that bank
operationalobjectOperational balance (internal use)
operational.balancenumberTotal operational balance in BRL
operational.balancesarrayBreakdown by bank

Query balance history

Query opening and closing balance for a specific date.

Route

GET /v2/balance/history

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParameterTypeRequiredDescription
datestringYesDate to query in YYYY-MM-DD format (e.g. "2025-08-11")

Request example:

curl --location 'https://api.pixtopay.com.br/v2/balance/history?date=2025-08-11' \
--header 'Authorization: API_KEY'

Response 200 - Success:

{
  "transactional": {
    "date": "2025-08-11",
    "balance": {
      "opening": 246.9,
      "closing": 1357.82
    },
    "balances": [
      {
        "bank": "STARKBANK",
        "opening_balance": 123.45,
        "closing_balance": 678.91
      },
      {
        "bank": "EFIPAY",
        "opening_balance": 123.45,
        "closing_balance": 678.91
      },
      {
        "bank": "GENIAL",
        "opening_balance": 0,
        "closing_balance": 0
      }
    ]
  },
  "operational": {
    "date": "2025-08-11",
    "balance": {
      "opening": 246.9,
      "closing": 1357.82
    },
    "balances": [
      {
        "bank": "STARKBANK",
        "opening_balance": 123.45,
        "closing_balance": 678.91
      },
      {
        "bank": "EFIPAY",
        "opening_balance": 123.45,
        "closing_balance": 678.91
      },
      {
        "bank": "GENIAL",
        "opening_balance": 0,
        "closing_balance": 0
      }
    ]
  }
}

Response Fields

ParameterTypeDescription
transactional.datestringQuery date
transactional.balanceobjectConsolidated balance for the day
transactional.balance.openingnumberOpening balance (start of day)
transactional.balance.closingnumberClosing balance (end of day)
transactional.balancesarrayBreakdown by bank
transactional.balances[].bankstringBank name
transactional.balances[].opening_balancenumberOpening balance at that bank
transactional.balances[].closing_balancenumberClosing balance at that bank
operationalobjectOperational balance data (same shape)

Response 400 - Invalid date:

{
  "type": "ValidationError",
  "message": "date must be in YYYY-MM-DD format"
}

Understanding balance types

Transactional balance

  • Definition: Balance available to perform transactions (PIX charges, payouts, etc.)
  • Usage: This is the balance you can use to create payouts and charges
  • Updates: Updated in real time with each transaction

Operational balance

  • Definition: Operational account balance, used for internal control
  • Usage: Typically used for reconciliation and financial control
  • Difference: May differ from transactional balance due to reserves and holds

Banks

PixToPay works with multiple banks to ensure redundancy and availability:

  • STARKBANK
  • EFIPAY
  • GENIAL
  • Other institutions: Contact sales to confirm availability of additional payment institutions.

Total balance is spread across these institutions to optimize processing and availability.

Use Cases

1. Check before creating a payout

async function canMakePayout(amount) {
  const response = await fetch("https://api.pixtopay.com.br/v2/balance", {
    headers: { Authorization: "YOUR_API_KEY" },
  });
  const data = await response.json();
  return data.transactional.balance >= amount;
}

2. Daily reconciliation

async function getDailyBalance(date) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/balance/history?date=${date}`,
    { headers: { Authorization: "YOUR_API_KEY" } }
  );
  return await response.json();
}

3. Balance dashboard

async function getBalanceSummary() {
  const response = await fetch("https://api.pixtopay.com.br/v2/balance", {
    headers: { Authorization: "YOUR_API_KEY" },
  });
  const data = await response.json();
 
  return {
    total: data.transactional.balance,
    byBank: data.transactional.balances.map((b) => ({
      bank: b.bank,
      amount: b.amount,
      percentage: ((b.amount / data.transactional.balance) * 100).toFixed(2),
    })),
  };
}

Important Notes

  • 🔒 Security: Endpoint available in production only to protect sensitive information
  • 🕐 Updates: Balances are updated in real time
  • 📊 History: History is available for any date from account creation onward
  • 💰 Currency: All amounts are in BRL (Brazilian Real)
  • 📅 Closing: Daily closing occurs at midnight (UTC-3)

Balance alerts

We recommend implementing alerts when:

  • ✅ Balance falls below a minimum operating threshold
  • ✅ Large balance swing in a short period
  • ✅ Discrepancy between transactional and operational balance
  • ✅ Negative balance at any institution
PDF ReceiptLimits