Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The /v1/transactions endpoint supports a rich set of query parameters. All filters are optional and can be combined. 
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

​
Payment Method

Filter by how the customer paid:
ValueDescription
QR_PHQR code payments
CARD_PRESENTCard payments (EMV, swipe, tap)
GET /v1/transactions?payment_method=CARD_PRESENT
Omit payment_method to get both QR and card-present transactions in a single response.

​
Merchant

Filter by merchant using the UUID from /v1/merchants: 
GET /v1/transactions?merchant_id=57846d47-d196-5c48-a881-4003b1d5aa98

​
Branch

Filter by branch using the UUID from /v1/branches: 
GET /v1/transactions?branch_id=f3febca6-7bd2-5d10-bcd7-1f796088e90c

​
Terminal

Filter by terminal using the activation code (the physical device identifier): 
GET /v1/transactions?activation_code=XXXX-XXXX-XXXX-XXXX

​
Status

Filter by one or more transaction statuses (comma-separated): 
# Single status
GET /v1/transactions?status=CAPTURED

# Multiple statuses
GET /v1/transactions?status=CAPTURED,PENDING,AUTHORIZED
StatusDescription
CAPTUREDPayment completed
AUTHORIZEDAuthorized, not yet captured
PENDINGAwaiting completion
DECLINEDDeclined by processor
VOIDEDCancelled before settlement
REFUNDEDFully refunded
PARTIALLY_REFUNDEDPartially refunded
FAILEDPayment failed
EXPIREDPayment expired
CANCELLEDPayment cancelled

​
Card Brand

Filter by card brand (card-present transactions only): 
GET /v1/transactions?card_brand=VISA
Accepted values: VISA, MASTERCARD, JCB, UNIONPAY

​
Date Range

Filter by transaction creation date using RFC 3339 timestamps: 
# Transactions in January 2026
GET /v1/transactions?date_from=2026-01-01T00:00:00Z&date_to=2026-01-31T23:59:59Z

# Transactions from a specific date onward
GET /v1/transactions?date_from=2026-04-15T00:00:00Z
Both date_from and date_to are optional. Use one or both to define the range.

​
Sorting

Control the order of results with sort_by and sort_order:
ParameterValuesDefault
sort_bycreated_at, updated_at, amountcreated_at
sort_orderasc, descdesc
# 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

ParameterTypeDefaultMax
page_sizeinteger20100
cursorstring(none)—

​
How It Works

  1. Make your initial request with page_size:
GET /v1/transactions?page_size=10
  1. The response includes pagination metadata:
{
  "data": [...],
  "pagination": {
    "page_size": 10,
    "has_more": true,
    "next_cursor": "eyJzb3J0X2J5IjoiY3Jl..."
  }
}
  1. Pass next_cursor to get the next page:
GET /v1/transactions?page_size=10&cursor=eyJzb3J0X2J5IjoiY3Jl...
  1. 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. The cursor remembers the full filter context: 
# 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: same filters, next cursor
GET /v1/transactions?merchant_id={uuid}&status=CAPTURED&sort_by=amount&sort_order=desc&page_size=20&cursor=eyJ...

​
Amount Details

Every transaction includes a consistent amount_details object with amounts in the smallest currency unit (cents): 
{
  "amount_details": {
    "amount_authorized": 16052,
    "amount_capturable": 0,
    "amount_received": 16052,
    "amount_refunded": 0
  }
}
FieldDescription
amount_authorizedAmount authorized by the processor
amount_capturableAmount available for capture
amount_receivedAmount actually received
amount_refundedAmount refunded to customer
Calculating GTV: Filter by status=CAPTURED and sum amount_received across all pages. This gives you the Gross Transaction Value for the filtered period.

​
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"

​
What’s Next?

API Reference

Full endpoint reference with request/response schemas

Authentication

API keys and entity scoping