Analytics

The analytics endpoints expose aggregated metrics over your transactional data: payments, refunds, and disputes. They power the dashboard you see in the merchant view, and they are reachable directly from the API for merchants who want to feed the same numbers into their own BI tools or reporting pipelines.

Scopes

Each metric resource is available under two scopes:

merchant — restricted to the merchant the API key belongs to. This is the most common scope for direct integrations.
org — aggregates across all merchants in the organisation. Reserved for organisation-level keys (PayFac admins).

The path looks like POST /analytics/v1/{scope}/metrics/{resource} where scope is one of the above and resource is one of payments, refunds, disputes.

Common request shape

All analytics endpoints share the same request body. The body is wrapped in an array so a single request can ask for multiple slices of data at once.

[
  {
    "timeRange": {
      "startTime": "2024-01-15T00:00:00Z",
      "endTime": "2024-01-22T23:59:59Z"
    },
    "metrics": ["payment_count", "payment_success_rate"],
    "source": "BATCH",
    "delta": false,
    "timeSeries": { "granularity": "G_ONE_DAY" },
    "groupByNames": ["currency"],
    "filters": {
      "currency": ["USD", "EUR"]
    }
  }
]

Field	Type	Required	Description
`timeRange.startTime`	ISO 8601 string	Yes	Start of the time window (inclusive).
`timeRange.endTime`	ISO 8601 string	Yes	End of the time window (inclusive).
`metrics`	array of strings	Yes	List of metric ids to compute. Resource-specific — see each endpoint.
`source`	string	Yes	Data backend. Use `BATCH` for analytics warehouse (default in the dashboard) or `LIVE` for real-time. `BATCH` is significantly cheaper.
`delta`	boolean	No	When `true`, returns the difference vs. the previous comparable window in addition to the absolute value. Defaults to `false`.
`timeSeries.granularity`	string	No	Bucket size when you want a time series back. One of `G_ONE_HOUR`, `G_ONE_DAY`, `G_ONE_WEEK`, `G_ONE_MONTH`. When omitted, only aggregates are returned.
`groupByNames`	array of strings	No	Dimensions to break down the metrics by (e.g. `["currency", "connector"]`).
`filters`	object	No	Restrict the rows that feed the aggregation. Each key is a field name (`currency`, `connector`, `payment_method`, `status`) and each value is an array of allowed values.

Response shape

All endpoints respond with the same envelope:

{
  "queryData": [
    { "currency": "USD", "payment_count": 1245, "payment_success_rate": 0.942 },
    { "currency": "EUR", "payment_count": 612, "payment_success_rate": 0.951 }
  ],
  "metaData": [
    { "total_payment_processed_amount": 8423500 }
  ]
}

queryData is the per-row aggregate (one row per groupByNames combination, or a single row when groupByNames is empty).
metaData carries totals that span all rows (useful when the merchant wants the overall total alongside the breakdown).

Endpoints

Resource	Path	Notes
Payments	`POST /analytics/v1/{scope}/metrics/payments`	Volume, success rate, processed amount, ticket size.
Refunds	`POST /analytics/v1/{scope}/metrics/refunds`	Refund count, success rate, processed amount.
Disputes	`POST /analytics/v1/{scope}/metrics/disputes`	Dispute status counts, total disputed, total lost.

Analytics

Scopes

Common request shape

Response shape

Endpoints

On this page