Filtering

Overview

Every filter on /v1/transactions is an optional query parameter, and they combine freely. This guide covers how they behave together, how to paginate, and how to total revenue correctly. For the canonical list of parameters and their accepted values, see the list-transactions reference.

GET /v1/transactions?merchant_id={uuid}&status=CAPTURED&date_from=2026-01-01T00:00:00Z&sort_by=amount&sort_order=desc&page_size=50

Filters

Each filter below is a recipe. The reference lists every accepted value.

Payment method - payment_method=CARD_PRESENT (or QR_PH, ECOM). Omit it to get every method in one response.
Merchant - merchant_id={uuid}, using a UUID from /v1/merchants.
Branch - branch_id={uuid}, using a UUID from /v1/branches.
Terminal - activation_code=XXXX-XXXX-XXXX-XXXX, the physical device identifier.
Status - one or more, comma-separated: status=CAPTURED,PENDING. See the reference for the full status list.
Card brand - card_brand=VISA (card transactions only).
Date range - date_from and date_to as RFC 3339 timestamps; use either or both.

# Captured card payments for a merchant, in January 2026
GET /v1/transactions?merchant_id={uuid}&payment_method=CARD_PRESENT&status=CAPTURED&date_from=2026-01-01T00:00:00Z&date_to=2026-01-31T23:59:59Z

Sorting

Control the order of results with sort_by and sort_order:

Parameter	Values	Default
`sort_by`	`created_at`, `updated_at`, `amount`	`created_at`
`sort_order`	`asc`, `desc`	`desc`

# Newest first (default)
GET /v1/transactions

# Oldest first
GET /v1/transactions?sort_by=created_at&sort_order=asc

# Highest amount first
GET /v1/transactions?sort_by=amount&sort_order=desc

# Most recently updated
GET /v1/transactions?sort_by=updated_at&sort_order=desc

Pagination

Results are cursor-paginated for efficient traversal of large datasets.

Parameters

Parameter	Type	Default	Max
`page_size`	integer	20	100
`cursor`	string	(none)	-

How It Works

Make your initial request with page_size:

GET /v1/transactions?page_size=10

The response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page_size": 10,
    "has_more": true,
    "next_cursor": "eyJzb3J0X2J5IjoiY3Jl..."
  }
}

Pass next_cursor to get the next page:

GET /v1/transactions?page_size=10&cursor=eyJzb3J0X2J5IjoiY3Jl...

Continue until has_more is false.

Don’t change sort_by between pages. Cursors are tied to the sort field used when the cursor was created. Changing sort_by mid-pagination returns a 400 error. Start a new query instead.

Combining Filters with Pagination

All filters work with pagination, but the cursor does not carry your filters - it encodes only the sort field, the sort position, and the source. You must resend every filter unchanged on each page.

# Page 1: captured transactions for a merchant, sorted by amount
GET /v1/transactions?merchant_id={uuid}&status=CAPTURED&sort_by=amount&sort_order=desc&page_size=20

# Page 2: repeat EVERY filter, add the cursor
GET /v1/transactions?merchant_id={uuid}&status=CAPTURED&sort_by=amount&sort_order=desc&page_size=20&cursor=eyJ...

Only a changed sort_by is detected and rejected with 400. Changing any other parameter mid-pagination (merchant, status, date range, page_size, sort_order, and so on) is not caught and returns incorrect results. Keep every filter identical across pages, or start a new query.

Amount Details

When the data is available, a transaction includes an amount_details object with amounts in the smallest currency unit (cents). The field is omitted (not null) when the breakdown is unavailable, so treat it as optional:

{
  "amount_details": {
    "amount_authorized": 16052,
    "amount_capturable": 0,
    "amount_received": 16052,
    "amount_refunded": 0
  }
}

Field	Description
`amount_authorized`	Amount authorized by the processor
`amount_capturable`	Amount available for capture
`amount_received`	Amount actually received
`amount_refunded`	Amount refunded to customer

Calculating GTV: Sum the top-level amount field across CAPTURED and PARTIALLY_REFUNDED transactions for the period. Do not sum amount_details.amount_received directly: for some card-present transactions it can be 0 while the top-level amount reflects the authorized value, so summing it undercounts.

Error Responses

Invalid filter values return 400 Bad Request:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "invalid status: INVALID_STATUS"
  }
}

Common errors:

Unknown query parameter → "unknown query parameter: foo"
Invalid status value → "invalid status: INVALID"
Invalid date format → "invalid date_from: must be RFC 3339"
Invalid sort field → "invalid sort_by: must be created_at, updated_at, or amount"

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

Overview

Filters

Sorting

Parameters

How It Works

Amount Details

Error Responses

What’s Next?

API Reference

Authentication

​Overview

​Filters

​Sorting

​Pagination

​Parameters

​How It Works

​Combining Filters with Pagination

​Amount Details

​Error Responses

​What’s Next?

API Reference

Authentication

Overview

Filters

Sorting

Pagination

Parameters

How It Works

Combining Filters with Pagination

Amount Details

Error Responses

What’s Next?