Use reporting endpoints

Although the PartnerHub and PayHub reporting tools allow partners and merchants to view reports, the reporting APIs offer more flexibility. For example,you may need to send daily settlement reporting details to their customers via an internal tool. Use the Payabli reporting APIs to get the data you need in the format you need it in.

The query API allows you to retrieve records related to various objects in Payabli, like customers, vendors, batches, transactions, and more.

The statistics API allows you to retrieve aggregated statistics for a certain period and mode, like total money out transactions, total money in transactions, number of new customers, total volume, and more.

This guide explains how to use the query and stats endpoints.

Build the request

First, choose an endpoint. If you’re testing, use the Sandbox endpoint. for your target environment. Make sure you use the right token for your selected environment. The API reference organizes query and statistic endpoints with their related object. For example, you can find all the reporting endpoints related to customers in the Customers section of the API reference.

Parameters

For a full list of available parameters, see the reference for the endpoint you choose. Most require at least an orgId or entry. Each endpoint may have other required fields. You can also use filters and conditions for most endpoints, so see Filters and Conditions Reference for examples and help understanding them.

Export formats

Most query endpoints support an exportFormat parameter that allows you to export data directly from the query endpoint in CSV or XLSX format. When you include exportFormat=csv or exportFormat=xlsx in your request, the endpoint returns the data in the specified format instead of JSON. This includes endpoints for batches, batch details, customers, transactions, transfers, settlements, payouts, chargebacks, subscriptions, vendors, organizations, and more.

For example, the batch query endpoints support export formats:

• Organization level: /Query/batches/org/{orgId}?exportFormat=csv
• Paypoint level: /Query/batches/{entry}?exportFormat=xlsx

Pagination

List endpoints are paginated. Two query parameters control the page size and where it starts (and let you pull everything at once):

• limitRecord — page size (number of records to return). Use 0 or a negative value to return all matching records.
• fromRecord — zero-based index of the first record to return.

Page through results by keeping limitRecord fixed and advancing fromRecord by that amount (0, then limitRecord, then 2 × limitRecord, and so on). The Summary block in the response tells you how many records and pages exist — see Response envelope.

Example request

Because there are infinite ways to build a request for one of the reporting endpoints, here are several example requests. Be sure to read the code comments for important context.

$
// This example queries transactions for the paypoint with entry ID e57ce00572.
$
// It filters the results to include only transactions with a customerFirstname that contains "Mary"
$
// with a transaction date of 05/08/2023, and limits the record count to 20. 
$
curl -X GET 'https://api-sandbox.payabli.com/api/Query/transactions/e57ce00572?parameters=customerFirstname%28ct%29%3DMary%26transactionDate%28eq%29%3D05%252F08%252F2023%26&limitRecord=20' \
>
    -H "accept: application/json" \
>
    -H "requestToken: <API TOKEN>"

Example response

A successful request returns a 200 response. By default, the response body is JSON. When you use the exportFormat parameter, the response is returned in the requested format (CSV or XLSX) instead of JSON. Response bodies vary by endpoint, so check the reference for the endpoint you’re using for expected fields.

Filters and conditions reference

Each Query endpoint accepts a set of field identifiers and conditions that allow you to filter and select data in the API.

Field identifiers and conditions are passed to the entrypoint path via parameters in the URL. The conditions are applied to the field in parentheses. The pattern is fieldName(condition)=value

For example: https://api.payabli.com/api/Query/transactions/entry?totalAmount(ge)=50

Here totalAmount is the field identifier to which you want to apply the comparison or condition. The condition is (ge), which in this case is greater than or equal to. The value base for the condition is 50, so the expression above is filtering records with the value in field totalAmount>=50.

Below you can see all the conventions for comparison you can use in the fields:

All the fields and conditions passed to the API entrypoint are inclusive, meaning that all conditions need to be satisfied to get the result set.

Date formats

All dates must be in ISO 8601 format, for example YYYY-MM-DDTHH:mm:ss.

Examples

The filters are appended as query parameters when making an API request. These examples are URL-encoded, the unencoded filter is included with the definition.

Response envelope

Query list endpoints return a JSON object with two top-level keys, Summary and Records:

1
{
2
  "Summary": {
3
    "totalRecords": 45,
4
    "totalPages": 9,
5
    "pageSize": 5
6
  },
7
  "Records": [ /* one page of results */ ]
8
}

• Records — the array of results for the current page.
• Summary.totalRecords — total records matching the query, across all pages.
• Summary.pageSize — records per page (mirrors limitRecord; equals totalRecords when you request all with limitRecord=0 or a negative value).
• Summary.totalPages — number of pages at the current page size (ceil(totalRecords / pageSize)).

Summary also carries endpoint-specific aggregate totals. For example, totalAmount appears on most endpoints, and the payout and settlement endpoints add status and fee totals. Use totalRecords / totalPages to drive pagination: keep requesting pages (advancing fromRecord) until you’ve retrieved totalRecords rows.

This envelope applies to the query list endpoints. The Statistic endpoints and exportFormat=csv / xlsx responses return different shapes.

Related resources

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