Pagination

Endpoints that return collections of resources use cursor-free, offset-based pagination. This page explains the query parameters, response format, and best practices for efficiently paginating through result sets.

Query Parameters

All paginated endpoints accept the following query parameters:

Pagination Parameters

Name	Type	Required	Description
page	integer	optional	Zero-based page index. The first page is 0 (not 1). Default: 0.
size	integer	optional	Number of items per page. Must be between 1 and 100. Default: 20.
sort	string	optional	Sort expression in the format field,direction. For example: createdAt,desc. Multiple sort fields can be specified by repeating the parameter.

Example Request

Fetch the second page of transfers, 10 per page, sorted by creation date descending:

curl -X GET "https://api.elaypay.app/api/v1/transfer/query/orders?page=1&size=10&sort=createdAt,desc" \
  -H "X-Api-Key: sk_live_abc123def456" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1709337600" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000"

Zero-based indexing

Pages are zero-indexed. page=0 returns the first page, page=1 returns the second page, and so on.

Response Format

Paginated responses wrap the result list in a data object that includes total count, page metadata, and navigation information.

200Paginated response

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "content": [
      {
        "transferId": "txn_001",
        "amount": "250.00",
        "currency": "USD",
        "status": "COMPLETED",
        "createdAt": "2026-03-01T10:30:00Z"
      },
      {
        "transferId": "txn_002",
        "amount": "75.50",
        "currency": "USD",
        "status": "COMPLETED",
        "createdAt": "2026-03-01T09:15:00Z"
      }
    ],
    "page": {
      "size": 10,
      "number": 1,
      "totalElements": 47,
      "totalPages": 5
    }
  }
}

Response Fields

Field	Type	Description
data.content	array	The list of items for the current page.
data.page.size	integer	The requested page size.
data.page.number	integer	The current page number (zero-based).
data.page.totalElements	integer	Total number of items across all pages.
data.page.totalPages	integer	Total number of pages. Computed as ceil(totalElements / size).

Sort Expressions

The sort parameter accepts a field name and a direction, separated by a comma:

sort=field,direction

Direction	Meaning
asc	Ascending order (A-Z, oldest first, smallest first)
desc	Descending order (Z-A, newest first, largest first)

Examples

Expression	Behavior
sort=createdAt,desc	Newest items first
sort=amount,asc	Smallest amounts first
sort=status,asc	Alphabetical by status

Multiple Sort Fields

To sort by multiple fields, repeat the sort parameter. The first field is the primary sort; subsequent fields break ties:

?sort=status,asc&sort=createdAt,desc

This sorts by status alphabetically, then by creation date (newest first) within each status group.

Sortable fields

Not all fields are sortable. Attempting to sort by a non-sortable field returns S012 (INVALID_PARAMETER). Common sortable fields include createdAt, updatedAt, amount, and status. Refer to the specific endpoint documentation for the list of supported sort fields.

Limits and Defaults

Parameter	Default	Minimum	Maximum
page	0	0	No upper limit (but pages beyond totalPages return empty content)
size	20	1	100

If you request a size greater than 100, the server will cap it at 100 without returning an error. If you request a negative page or size, the server returns S012 (INVALID_PARAMETER).

Iterating Through All Pages

Here is a JavaScript example that fetches all pages of a paginated endpoint:

async function fetchAllPages(path, apiKey, apiSecret) {
  const allItems = [];
  let page = 0;
  let totalPages = 1; // Will be updated after the first request

  while (page < totalPages) {
    const response = await apiRequest(
      'GET',
      `${path}?page=${page}&size=100&sort=createdAt,desc`,
      null,
      apiKey,
      apiSecret
    );

    if (!response.success) {
      throw new Error(`API error: ${response.code} - ${response.message}`);
    }

    allItems.push(...response.data.content);
    totalPages = response.data.page.totalPages;
    page++;
  }

  return allItems;
}

// Usage
const allTransfers = await fetchAllPages(
  '/api/v1/transfer/query/orders',
  'sk_live_abc123def456',
  'your-api-secret-here'
);

Performance consideration

Fetching all pages in a loop works well for small to medium datasets. For very large datasets (thousands of items), consider whether you truly need all records at once. Often, you can filter by date range or status to reduce the result set, or process items page by page without accumulating them all in memory.

Empty Results

When a page has no items (either because the collection is empty or you requested a page beyond the last), the response returns an empty content array with accurate metadata:

200Empty page

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "content": [],
    "page": {
      "size": 20,
      "number": 0,
      "totalElements": 0,
      "totalPages": 0
    }
  }
}

Tips for Efficient Pagination

Use filters to reduce result sets

Most list endpoints support query filters (by status, date range, ID prefix, etc.) in addition to pagination. Apply filters to narrow results before paginating, rather than fetching everything and filtering client-side.

Choose an appropriate page size

The default size of 20 is suitable for UI-driven pagination. For batch processing or data export, use size=100 to minimize the number of HTTP round-trips. For mobile clients or low-bandwidth scenarios, consider a smaller size like 10.

Handle concurrent modifications

In highly active systems, items may be created or deleted between page requests. This can cause items to shift between pages (appearing twice or being skipped). If exact-once processing is critical, use date-range filters with a fixed timestamp boundary instead of relying on page numbers alone.

Cache the total count

The totalElements and totalPages values are computed on every request. If you are building a UI with page numbers and the total count does not change frequently, cache these values after the first request rather than re-reading them on every page navigation.