Métricas
Volumes de Pagamentos

Volumes de Pagamentos (Cash-out)

Consulte volumes e valores de pagamentos por status em uma data específica.

Endpoint Disponível

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

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

Consultar volumes de pagamentos

Route

GET /v2/metrics/withdrawals

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
datestringSimData para consulta no formato "YYYY-MM-DD" (ex: "2025-08-04")

Exemplo de requisição:

curl --location 'https://api.pixtopay.com.br/v2/metrics/withdrawals?date=2025-08-04' \
--header 'Authorization: API_KEY'

Resposta 200 - Sucesso:

{
  "date": "2025-08-04",
  "pending": {
    "qtd": 6,
    "amount": 220.45
  },
  "paid": {
    "qtd": 12567,
    "amount": 3353503.72
  },
  "rejected": {
    "qtd": 90,
    "amount": 10853.93
  },
  "reversed": {
    "qtd": 2,
    "amount": 5972
  }
}

Campos da Resposta

ParâmetroTipoDescrição
datestringData da consulta
pendingobjectPagamentos pendentes (status 0)
pending.qtdintegerQuantidade de pagamentos pendentes
pending.amountnumberValor total dos pagamentos pendentes
paidobjectPagamentos aprovados (status 1)
paid.qtdintegerQuantidade de pagamentos aprovados
paid.amountnumberValor total dos pagamentos aprovados
rejectedobjectPagamentos rejeitados (status 3)
rejected.qtdintegerQuantidade de pagamentos rejeitados
rejected.amountnumberValor total dos pagamentos rejeitados
reversedobjectPagamentos revertidos
reversed.qtdintegerQuantidade de pagamentos revertidos
reversed.amountnumberValor total dos pagamentos revertidos

Status de Pagamentos

StatusDescrição
0Pagamento criado, aguardando processamento
1Pagamento aprovado/concluído
2Pagamento cancelado
3Pagamento rejeitado
4Pagamento em processamento

Casos de Uso

1. Dashboard diário de pagamentos

async function getDailyWithdrawals(date) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/metrics/withdrawals?date=${date}`,
    {
      headers: { Authorization: "YOUR_API_KEY" },
    }
  );
  const data = await response.json();
 
  return {
    total: data.paid.amount,
    count: data.paid.qtd,
    pending: data.pending.amount,
    rejected: data.rejected.amount,
  };
}

2. Taxa de sucesso

async function getSuccessRate(date) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/metrics/withdrawals?date=${date}`,
    { headers: { Authorization: "YOUR_API_KEY" } }
  );
  const data = await response.json();
 
  const total = data.paid.qtd + data.rejected.qtd;
  const successRate = ((data.paid.qtd / total) * 100).toFixed(2);
  const rejectionRate = ((data.rejected.qtd / total) * 100).toFixed(2);
 
  return {
    total,
    approved: data.paid.qtd,
    rejected: data.rejected.qtd,
    successRate: `${successRate}%`,
    rejectionRate: `${rejectionRate}%`,
  };
}

3. Análise de rejeições

async function getRejectionAnalysis(date) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/metrics/withdrawals?date=${date}`,
    { headers: { Authorization: "YOUR_API_KEY" } }
  );
  const data = await response.json();
 
  return {
    rejected: {
      count: data.rejected.qtd,
      amount: data.rejected.amount,
      avgValue: (data.rejected.amount / data.rejected.qtd).toFixed(2),
    },
    reversed: {
      count: data.reversed.qtd,
      amount: data.reversed.amount,
    },
    impactPercentage: (
      ((data.rejected.amount + data.reversed.amount) /
        (data.paid.amount + data.rejected.amount + data.reversed.amount)) *
      100
    ).toFixed(2),
  };
}

4. Comparativo com período anterior

async function compareWithPreviousPeriod(currentDate, previousDate) {
  const [current, previous] = await Promise.all([
    fetch(
      `https://api.pixtopay.com.br/v2/metrics/withdrawals?date=${currentDate}`,
      { headers: { Authorization: "YOUR_API_KEY" } }
    ).then((r) => r.json()),
    fetch(
      `https://api.pixtopay.com.br/v2/metrics/withdrawals?date=${previousDate}`,
      { headers: { Authorization: "YOUR_API_KEY" } }
    ).then((r) => r.json()),
  ]);
 
  return {
    current: {
      amount: current.paid.amount,
      count: current.paid.qtd,
    },
    previous: {
      amount: previous.paid.amount,
      count: previous.paid.qtd,
    },
    growth: {
      amount: (
        ((current.paid.amount - previous.paid.amount) / previous.paid.amount) *
        100
      ).toFixed(2),
      count: (
        ((current.paid.qtd - previous.paid.qtd) / previous.paid.qtd) *
        100
      ).toFixed(2),
    },
  };
}

Observações Importantes

  • 🔒 Produção: Endpoint disponível apenas em produção
  • 📊 Dados agregados: Métricas são pré-calculadas para performance
  • 🕐 Atualização: Dados atualizados em tempo real
  • 📅 Período: Consulte qualquer data a partir da criação da conta
  • 💰 Moeda: Todos os valores em BRL (Real Brasileiro)
  • ⏰ Timezone: Todas as datas em UTC-3 (Brasília)

Insights de Negócio

Qualidade operacional

Monitore:

  • Taxa de rejeição de pagamentos
  • Volume de pagamentos reversões
  • Valor médio por transação
  • Períodos de maior volume

Gestão financeira

Acompanhe:

  • Volume diário de saída
  • Fluxo de caixa (compare com deposits)
  • Saldo necessário para operação
  • Previsão de pagamentos

Performance

Analise:

  • Taxa de sucesso ao longo do tempo
  • Horários de pico
  • Dias da semana com mais pagamentos
  • Tendências de crescimento

Principais Métricas

Taxa de Sucesso

Taxa de Sucesso = (Aprovados / (Aprovados + Rejeitados)) * 100

Taxa de Rejeição

Taxa de Rejeição = (Rejeitados / (Aprovados + Rejeitados)) * 100

Valor Médio

Valor Médio = Total Amount / Total Count

Impacto de Falhas

Impacto = (Rejeitados + Revertidos) / Total * 100
Bancos dos DepósitosBancos dos Pagamentos