Payout banks

List the banks most used as destinations for your payouts in a specific period.

Available endpoint

Production: https://api.pixtopay.com.br/v2/metrics/withdrawals/banks

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

Query payout banks

Route

GET /v2/metrics/withdrawals/banks

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query parameters

Parameter	Type	Required	Description
`start`	string	Yes	Start date/time in `"YYYY-MM-DD HH:MM:SS"` format
`end`	string	Yes	End date/time in `"YYYY-MM-DD HH:MM:SS"` format

Request example:

curl --location 'https://api.pixtopay.com.br/v2/metrics/withdrawals/banks?start=2025-08-04%2016:00:00&end=2025-08-04%2017:00:00' \
--header 'Authorization: API_KEY'

Response `200` - Success:

[
  {
    "count": 3456,
    "ispb": "18236120",
    "bank_name": "NU PAGAMENTOS - IP"
  },
  {
    "count": 2891,
    "ispb": "22896431",
    "bank_name": "PICPAY"
  },
  {
    "count": 2234,
    "ispb": "00360305",
    "bank_name": "CAIXA ECONOMICA FEDERAL"
  },
  {
    "count": 1987,
    "ispb": "00416968",
    "bank_name": "BANCO INTER"
  },
  {
    "count": 1654,
    "ispb": "90400888",
    "bank_name": "BCO SANTANDER (BRASIL) S.A."
  }
]

Response fields

Parameter	Type	Description
`count`	integer	Number of transactions per bank
`ispb`	string	Bank ISPB
`bank_name`	string	Bank name

Note: The response is sorted by count in descending order (banks with the most transactions first).

Use cases

1. Top 10 destination banks

async function getTopDestinationBanks(start, end) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/metrics/withdrawals/banks?start=${start}&end=${end}`,
    { headers: { Authorization: "YOUR_API_KEY" } }
  );
  const banks = await response.json();
 
  const total = banks.reduce((sum, b) => sum + b.count, 0);
 
  return banks.slice(0, 10).map((bank) => ({
    name: bank.bank_name,
    ispb: bank.ispb,
    transactions: bank.count,
    percentage: ((bank.count / total) * 100).toFixed(2) + "%",
  }));
}

2. Dispersion analysis

async function getDispersionAnalysis(start, end) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/metrics/withdrawals/banks?start=${start}&end=${end}`,
    { headers: { Authorization: "YOUR_API_KEY" } }
  );
  const banks = await response.json();
 
  const total = banks.reduce((sum, b) => sum + b.count, 0);
  const uniqueBanks = banks.length;
 
  // Concentration in top 5
  const top5Count = banks.slice(0, 5).reduce((sum, b) => sum + b.count, 0);
  const top5Concentration = ((top5Count / total) * 100).toFixed(2);
 
  // Diversification index
  const diversity = banks.map((b) => {
    const p = b.count / total;
    return -p * Math.log2(p);
  });
  const diversityIndex = diversity.reduce((sum, d) => sum + d, 0).toFixed(2);
 
  return {
    totalBanks: uniqueBanks,
    totalTransactions: total,
    top5Concentration: `${top5Concentration}%`,
    diversityIndex,
  };
}

3. Compare periods

async function compareBankUsage(
  period1Start,
  period1End,
  period2Start,
  period2End
) {
  const [period1, period2] = await Promise.all([
    fetch(
      `https://api.pixtopay.com.br/v2/metrics/withdrawals/banks?start=${period1Start}&end=${period1End}`,
      { headers: { Authorization: "YOUR_API_KEY" } }
    ).then((r) => r.json()),
    fetch(
      `https://api.pixtopay.com.br/v2/metrics/withdrawals/banks?start=${period2Start}&end=${period2End}`,
      { headers: { Authorization: "YOUR_API_KEY" } }
    ).then((r) => r.json()),
  ]);
 
  const period2Map = new Map(period2.map((b) => [b.ispb, b.count]));
 
  return period1.slice(0, 10).map((bank) => {
    const prevCount = period2Map.get(bank.ispb) || 0;
    const growth = prevCount
      ? (((bank.count - prevCount) / prevCount) * 100).toFixed(2)
      : "N/A";
 
    return {
      bank: bank.bank_name,
      current: bank.count,
      previous: prevCount,
      growth: growth !== "N/A" ? `${growth}%` : growth,
    };
  });
}

4. Monitor issues by bank

async function monitorBankIssues(start, end, rejectedTransactions) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/metrics/withdrawals/banks?start=${start}&end=${end}`,
    { headers: { Authorization: "YOUR_API_KEY" } }
  );
  const banks = await response.json();
 
  // Correlate with rejections (sample data — you would fetch this separately)
  const rejectionsByBank = rejectedTransactions.reduce((acc, t) => {
    acc[t.bank_ispb] = (acc[t.bank_ispb] || 0) + 1;
    return acc;
  }, {});
 
  return banks.map((bank) => {
    const rejected = rejectionsByBank[bank.ispb] || 0;
    const successRate = (((bank.count - rejected) / bank.count) * 100).toFixed(
      2
    );
 
    return {
      bank: bank.bank_name,
      total: bank.count,
      rejected,
      successRate: `${successRate}%`,
      alert: successRate < 95 ? "⚠️ LOW RATE" : "✅ OK",
    };
  });
}

Business insights

Beneficiary profile

Identify:

Preferred banks: Where your customers receive funds
Digital vs traditional: Beneficiary profile
Concentration: Reliance on a small set of banks
Trends: Changes over time

Process optimization

Use the data to:

Identify banks with processing issues
Prioritize testing on the most-used banks
Plan maintenance during low-volume windows
Build bank-specific reports

Bank relationships

Partnership insights:

Negotiate fees with the most-used banks
Establish specific SLAs
Create direct support channels
Build optimized integrations

Important notes

🔒 Production: Endpoint available only in production
📊 Sorting: Results ordered by volume (descending)
🕐 Flexible period: Query any period (hour, day, month)
🏦 Full coverage: Includes all banks in the Brazilian PIX system
💡 ISPB: Use ISPB to uniquely identify banks
⏰ Timezone: Dates/times in UTC-3 (Brasília)

Differences: deposits vs withdrawals banks

Deposits (payers)

Shows where money comes from
Profile of your customers / payers
Usually higher volume (many people paying)

Withdrawals (beneficiaries)

Shows where money goes
Profile of your beneficiaries
May show lower diversity

Key metrics

Concentration

Top 5 concentration = (Sum of top 5 / Total) * 100

Diversification (Shannon index)

H = -Σ(pi * log2(pi))
where pi = share of transactions for bank i

The higher H, the greater the diversification.

Growth rate per bank

Growth = ((Current - Previous) / Previous) * 100

Withdrawal Volumes Webhooks