Metrics
Withdrawal Volumes

Payout volumes (Cash-out)

Query volumes and amounts of payouts by status for a specific date.

Available endpoint

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

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

Query payout volumes

Route

GET /v2/metrics/withdrawals

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query parameters

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

Request example:

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

Response 200 - Success:

{
  "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
  }
}

Response fields

ParameterTypeDescription
datestringQuery date
pendingobjectPending payouts (status 0)
pending.qtdintegerNumber of pending payouts
pending.amountnumberTotal amount of pending payouts
paidobjectApproved payouts (status 1)
paid.qtdintegerNumber of approved payouts
paid.amountnumberTotal amount of approved payouts
rejectedobjectRejected payouts (status 3)
rejected.qtdintegerNumber of rejected payouts
rejected.amountnumberTotal amount of rejected payouts
reversedobjectReversed payouts
reversed.qtdintegerNumber of reversed payouts
reversed.amountnumberTotal amount of reversed payouts

Payout statuses

StatusDescription
0Payout created, awaiting processing
1Payout approved / completed
2Payout canceled
3Payout rejected
4Payout in processing

Use cases

1. Daily payout dashboard

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

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

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. Comparison with previous period

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),
    },
  };
}

Important notes

  • 🔒 Production: Endpoint available only in production
  • 📊 Aggregated data: Metrics are precomputed for performance
  • 🕐 Updates: Data updated in real time
  • 📅 Period: Query any date from account creation onward
  • 💰 Currency: All amounts in BRL (Brazilian Real)
  • ⏰ Timezone: All dates in UTC-3 (Brasília)

Business insights

Operational quality

Monitor:

  • Payout rejection rate
  • Volume of payout reversals
  • Average value per transaction
  • Periods with highest volume

Financial management

Track:

  • Daily outbound volume
  • Cash flow (compare with deposits)
  • Balance required for operations
  • Payout forecasts

Performance

Analyze:

  • Success rate over time
  • Peak hours
  • Weekdays with the most payouts
  • Growth trends

Key metrics

Success rate

Success rate = (Approved / (Approved + Rejected)) * 100

Rejection rate

Rejection rate = (Rejected / (Approved + Rejected)) * 100

Average amount

Average amount = Total amount / Total count

Failure impact

Impact = (Rejected + Reversed) / Total * 100
Deposit BanksWithdrawal Banks