Métricas
Bancos dos Pagamentos

Bancos dos Pagamentos

Liste os bancos mais utilizados como destino dos seus pagamentos em um período específico.

Endpoint Disponível

  • Produção: https://api.pixtopay.com.br/v2/metrics/withdrawals/banks

⚠️ Atenção: Este endpoint está disponível apenas em produção.

Consultar bancos dos pagamentos

Route

GET /v2/metrics/withdrawals/banks

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
startstringSimData/hora inicial no formato "YYYY-MM-DD HH:MM:SS"
endstringSimData/hora final no formato "YYYY-MM-DD HH:MM:SS"

Exemplo de requisição:

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'

Resposta 200 - Sucesso:

[
  {
    "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."
  }
]

Campos da Resposta

ParâmetroTipoDescrição
countintegerNúmero de transações do banco
ispbstringISPB do banco
bank_namestringNome do banco

Nota: A resposta é ordenada por count em ordem decrescente (bancos com mais transações primeiro).

Casos de Uso

1. Top 10 bancos de destino

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. Análise de dispersão

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;
 
  // Concentração nos top 5
  const top5Count = banks.slice(0, 5).reduce((sum, b) => sum + b.count, 0);
  const top5Concentration = ((top5Count / total) * 100).toFixed(2);
 
  // Índice de diversificação
  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. Comparar períodos

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. Monitorar problemas por banco

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();
 
  // Correlacionar com rejeições (dados fictícios - você precisaria buscar isso)
  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 ? "⚠️ BAIXA TAXA" : "✅ OK",
    };
  });
}

Insights de Negócio

Perfil dos beneficiários

Identifique:

  • Bancos preferidos: Onde seus clientes recebem
  • Digital vs Tradicional: Perfil dos beneficiários
  • Concentração: Dependência de poucos bancos
  • Tendências: Mudanças ao longo do tempo

Otimização de processos

Use os dados para:

  • Identificar bancos com problemas de processamento
  • Priorizar testes com bancos mais utilizados
  • Planejar manutenções em horários de baixo volume
  • Desenvolver relatórios específicos por banco

Relacionamento com bancos

Insights para parcerias:

  • Negociar tarifas com bancos mais utilizados
  • Estabelecer SLAs específicos
  • Criar canais diretos de suporte
  • Desenvolver integrações otimizadas

Observações Importantes

  • 🔒 Produção: Endpoint disponível apenas em produção
  • 📊 Ordenação: Resultados ordenados por volume (decrescente)
  • 🕐 Período flexível: Consulte qualquer período (hora, dia, mês)
  • 🏦 Cobertura completa: Inclui todos os bancos do sistema PIX brasileiro
  • 💡 ISPB: Use o ISPB para identificar bancos de forma única
  • ⏰ Timezone: Datas/horas em UTC-3 (Brasília)

Diferenças: Deposits vs Withdrawals Banks

Deposits (Pagadores)

  • Mostra de onde o dinheiro vem
  • Perfil dos seus clientes/pagadores
  • Geralmente maior volume (muitos pagando)

Withdrawals (Beneficiários)

  • Mostra para onde o dinheiro vai
  • Perfil dos seus beneficiários
  • Pode ter menor diversidade

Principais Métricas

Concentração

Concentração Top 5 = (Soma Top 5 / Total) * 100

Diversificação (Shannon Index)

H = -Σ(pi * log2(pi))
onde pi = proporção de transações do banco i

Quanto maior H, maior a diversificação.

Taxa de Crescimento por Banco

Crescimento = ((Atual - Anterior) / Anterior) * 100
Volumes de PagamentosWebhooks