Choose a data source for analytics

Applies to:DevelopersPartners

When you build a dashboard, a merchant scorecard, or your own reports, you can get Payabli data from three sources: the statistics API, the query API, and webhooks. Each one answers a different kind of question. Picking the right one up front saves you from rebuilding totals Payabli already calculates, or from computing a metric on data that can’t support it.

For how to build requests, filter, and paginate, see Use reporting endpoints. For the Portal dashboard, Portal reports, and Amigo Insights, see Reporting and analytics overview.

Compare the data sources

Each source returns a different shape of data.

Source	What you get	Use it for
Statistics API	Totals that Payabli already calculated, one row per period (hour, day, week, or month) for an organization, paypoint, customer, or vendor. JSON only.	Volume, transaction counts, payment method mix, and new customer or vendor counts over time.
Query API	Individual records, like transactions, chargebacks, batches, settlements, customers, vendors, and bills. Filterable, paginated, and exportable as CSV or XLSX.	Any metric that needs record-level detail, a filter the statistics API doesn’t offer, or a breakdown by customer, vendor, or status.
Webhooks	A notification each time an event happens, like a payment approval or a new chargeback.	Reacting to events as they happen, and keeping your own copy of activity up to date without polling.

Start with the statistics API when the metric is a total or a count over time. Move to the query API when you need to see or filter the records behind the total. Add webhooks when you need to act on events as they happen.

When the statistics API is enough

The statistics endpoints return pre-calculated totals, so one call can replace paging through thousands of transactions. Use them for metrics like these:

Pay In and Pay Out volume and transaction counts per month, week, day, or hour
Payment method mix, like card compared to ACH, using the per-method counts and volumes
New customers or new vendors per period
Card chargeback and ACH return counts and volumes per period
Upcoming subscription renewals over the next 30, 60, 90, or more days

The statistics endpoints are:

GET /Statistic/basic for an organization (level 0) or a paypoint (level 2). It’s the only statistics endpoint that accepts a custom date range, using mode=custom with startDate and endDate.
GET /Statistic/customerbasic for one customer’s Pay In activity.
GET /Statistic/vendorbasic for one vendor’s bills, broken down by bill status.
GET /Statistic/subscriptions for renewals that are coming up.

When you need the query API

The statistics API can’t answer every question. Use the query API in these cases:

The metric involves declines. The statistics API counts approved transactions only, so it can’t tell you a decline rate. Query transactions to see every status.
You need a breakdown the statistics API doesn’t have. For example, a ranking of every customer on a paypoint by volume. /Statistic/customerbasic covers one customer per call, so query the transactions and group them yourself.
You need a filter the statistics API doesn’t have. The statistics endpoints filter by entity and period only. Query endpoints accept field filters, like an amount range or a customer ZIP code.
You need the individual records. For example, to work with each dispute or reconcile a batch.
You need a file. Most query endpoints export CSV or XLSX. The statistics endpoints return JSON only.

When you query, the Summary block in the response also carries totals for the matching records, like totalAmount. For a filtered total, you might not need to add up the rows yourself.

When to add webhooks

The statistics and query APIs tell you what’s in Payabli when you ask. Webhooks tell you when something changes. Use webhooks to update a dashboard as payments arrive, to trigger your own workflows, or to keep your own data store current without polling on a schedule.

To build a history, pair webhooks with the query API. Query the past records once, then let webhooks keep your copy up to date. Payabli retries a failed webhook only twice, so an outage on your side can leave gaps. Run a regular query, like a daily transactions query with date filters, to catch anything you missed, or resend failed notifications. To decide between webhooks and polling for a specific workflow, see Decision guide: Webhooks vs polling.

Avoid common mistakes

These details in the statistics responses lead to wrong metrics if you miss them:

Don’t compare net volume to gross volume. /Statistic/basic volumes are net of fees. /Statistic/customerbasic volume is gross, before fees. Pick one basis for a metric and stay with it.
Don’t add up customer or vendor totals across periods. inCustomers and outCustomers are running totals through the end of each period, not counts for that period. For new customers or vendors per period, use inNewCustomers and outNewCustomers.
Don’t add subscription payments to the total. inSubscriptionsPaid is part of inTransactions, not extra transactions on top of it.
Don’t treat subscription statistics as revenue. /Statistic/subscriptions is a forecast of renewals that are coming up. For subscription payments already collected, use inSubscriptionsPaid and inSubscriptionsPaidVolume from /Statistic/basic.
Read subscription intervals as separate ranges. In /Statistic/subscriptions, 60 covers days 31 through 60 and 90 covers days 61 through 90. They don’t include the shorter ranges. Use all to get every range in one call.

On the Pay In side of /Statistic/basic, the per-method counts don’t overlap, and they add up to inTransactions. You can safely use them for a payment method breakdown.

Build a monthly scorecard for one paypoint

To show a merchant their last 12 months of Pay In activity, call /Statistic/basic once at the paypoint level with mode=m12 and freq=m:

curl -X GET https://api-sandbox.payabli.com/api/Statistic/basic/m12/m/2/{entryId} \
    -H "accept: application/json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Each row in the response is one month. From those rows, you can chart:

Monthly volume and transaction count, from inTransactionsVolume and inTransactions
Payment method mix, from inCardVolume, inACHVolume, and the other per-method volumes
New customers per month, from inNewCustomers
Chargebacks and returns per month, from inCardChargeBacks and inACHReturns

To add a decline rate or a top-customers list, query the paypoint’s transactions for the same date range and calculate them from the records. The transactions query returns only the last 60 days by default, so add transactionDate filters to cover all 12 months.

Build an organization dashboard

For an organization-wide trend line, call /Statistic/basic at the organization level (level 0) with the organization ID as entryId. To compare paypoints side by side, make one call per paypoint at level 2. Use the query API to list the organization’s paypoints first.

The statistics API doesn’t cover boarding. To track boarding progress, list the boarding applications instead.

See these related resources to help you get the most out of Payabli.