Paginate through results

Several Payments Direct API endpoints return paginated results when a list could contain many records. The API uses two pagination styles depending on the endpoint:

• Token-based pagination for identities, financial instruments, and payment search. The response includes an opaque nextToken value that you pass to retrieve the next page.
• Offset-based pagination for ledger transactions. You specify a starting record index (offset) and the number of records to return (page-size).

The table below summarizes which style applies to each paginated endpoint.

Token-based pagination uses an opaque string token to mark your position in a result set. When the API returns a nextToken in the response, more results are available. When nextToken is absent, you have reached the last page.

Tokens are opaque and may change between releases. Do not attempt to decode, parse, or construct token values.

For GET /v3/identities and GET /v3/identities/{identity-id}/financial-instruments, pass pagination parameters as query parameters.

Request parameters:

Example: First page

curl -X GET "https://{base-url}/v3/identities?limit=25" \
  -H "Authorization: Bearer <access_token>"

Example response (more pages available):

{
  "data": [
    { "identityId": "abc123", "identityType": "INDIVIDUAL", "..." },
    { "..." }
  ],
  "nextToken": "eyJrZXkxIjoidmFsdWUifQ=="
}

Example: Subsequent page

curl -X GET "https://{base-url}/v3/identities?limit=25&next-token=eyJrZXkxIjoidmFsdWUifQ==" \
  -H "Authorization: Bearer <access_token>"

When the response does not include a nextToken field, you have retrieved all available records.

The POST /v3/payments/filter endpoint uses token-based pagination, but the pagination parameters are passed in the request body rather than as query parameters.

Request body pagination fields:

Example: First page

curl -X POST "https://{base-url}/v3/payments/filter" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "paymentStates": ["COMPLETED"]
    },
    "sort": {
      "sortField": "CREATED_AT",
      "sortDirection": "DESC"
    },
    "page": {
      "size": 20
    }
  }'

Example response (more pages available):

{
  "data": [ { "..." } ],
  "filter": { "..." },
  "sort": { "..." },
  "page": {
    "size": 20,
    "lastPageToken": "eyJsYXN0SWQiOiJhYmMxMjMifQ=="
  }
}

Example: Subsequent page

Include the lastPageToken value from the previous response in the next request body:

{
  "page": {
    "size": 20,
    "lastPageToken": "eyJsYXN0SWQiOiJhYmMxMjMifQ=="
  }
}

When the response does not include a page.lastPageToken field, you have retrieved all matching payments.

The GET /v2/ledger-transactions endpoint uses offset-based pagination. You control the result window with two parameters: page-size (how many records to return) and offset (how many records to skip).

Request parameters:

The response includes a total field with the overall count of matching records. Use total, pageSize, and pageElements to determine whether additional pages exist.

Response fields:

Example: First page

curl -X GET "https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25" \
  -H "Authorization: Bearer <access_token>"

Example response:

{
  "offset": 0,
  "pageSize": 25,
  "pageElements": 25,
  "total": 83,
  "statementTransactions": [ { "..." } ]
}

Example: Second page

With total=83 and pageSize=25, the second page starts at offset=25:

curl -X GET "https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25&offset=25" \
  -H "Authorization: Bearer <access_token>"

You have retrieved all records when offset + pageElements >= total.

Use the maximum page size for bulk retrieval. When your goal is to retrieve all records (for example, for reconciliation), set limit or page-size to the maximum allowed value to minimize the number of requests.

Check for the absence of nextToken, not its value. For token-based endpoints, the correct signal that you have reached the last page is the absence of nextToken (or page.lastPageToken) in the response, not a specific token value.

Do not modify or construct tokens. Tokens are opaque. Building logic that parses or concatenates token values will break when the token format changes.

Account for records added during retrieval. Offset-based pagination over an actively changing result set can produce gaps or duplicates. For ledger transactions, use a fixed time range (start-dttm and end-dttm) to ensure the result set does not change while you paginate through it.

Do not cache tokens across sessions. Tokens are only valid for the session in which they were issued. Always start a fresh pagination sequence for a new retrieval job.