Pagination and filtering

Laravel pagination shapes

Wallet transactions, ledger entries, audit records, payouts, and settlements use pagination with a default page size of 20. Send page and per_page; do not request an unbounded collection. Some endpoints place pagination fields inside data, while merchant transactions return an item array plus a separate meta object. The reference documents the exact envelope for each route.

Stable ordering

Most lists are currently ordered by created_at descending. When synchronizing a long history, persist the last identifier and timestamp you observed and account for new rows appearing between page requests. Page number alone is not a durable financial synchronization cursor.

Filters

Payouts and settlements support wallet_id, status, and business_id according to actor scope. Reports require from and to dates. A customer application must not send business_id in an attempt to broaden its scope; the server enforces authenticated context.

Limits and performance

Use the smallest per_page that satisfies your interface and debounce repeated dashboard requests. Aggregate reports are not a reason to download every ledger entry and recalculate balance. Balance and ledger serve different purposes: balance is an operational snapshot, while the ledger is the immutable audit trail.

Completion

Stop when current_page >= last_page or the returned collection is empty. Deduplicate records by UUID or primary identifier when resuming a page after an interrupted synchronization.