Overview

Pagination

The Payonify API uses cursor-based pagination for list endpoints to allow you to iterate through large collections of resources. Our pagination implementation provides a consistent and efficient way to navigate through large result sets.

How Pagination Works

When you make a request to a list endpoint such as /v1/charges, /v1/refunds, or /v1/checkout/sessions, the API returns a paginated response that includes:

• A data array containing the objects in the current page
• A paging object with metadata about the current page and cursors for navigating to other pages

Pagination Response Format

Code
 
{
  "data": [
    { ... },
    { ... }
  ],
  "object": "list",
  "paging": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": "cursor_abc123",
    "end_cursor": "cursor_xyz789",
    "page_size": 10
  }
}

Pagination Parameters

When querying list endpoints, below are the accepted parameters:

Parameter	Description
first	The number of objects to return per page
after	The cursor to use as the starting point for the next page
last	The number of objects to return per page
before	The cursor to use as the starting point for the previous page

Note: first and last are mutually exclusive. You can only use one of them at a time. first is used with after and last is used with before.

Example: Iterating Through Pages

First Request

Code
 
curl https://api.payonify.com/v1/charges?first=10 \
  -u "pk_test_abc123...:sk_test_xyz789..."

Response

Code
 
{
  "data": [
    { "id": "ch_1", ... },
    { "id": "ch_2", ... },
    { "id": "ch_3", ... },
    { "id": "ch_4", ... },
    { "id": "ch_5", ... }
  ],
  "object": "list",
  "paging": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": null,
    "end_cursor": "cursor_abc123",
    "page_size": 10
  }
}

Fetching the Next Page

To get the next page, use the end_cursor from the previous response as the after parameter:

Code
 
curl https://api.payonify.com/v1/charges?first=10&after=cursor_abc123 \
  -u "pk_test_abc123...:sk_test_xyz789..."

Response

Code
 
{
  "data": [
    { "id": "ch_6", ... },
    { "id": "ch_7", ... },
    { "id": "ch_8", ... },
    { "id": "ch_9", ... },
    { "id": "ch_10", ... }
  ],
  "object": "list",
  "paging": {
    "has_previous_page": true,
    "has_next_page": true,
    "start_cursor": "cursor_def456",
    "end_cursor": "cursor_ghi789",
    "page_size": 10
  }
}

Fetching the Previous Page

To go back to the previous page, use the start_cursor from the current response as the before parameter:

Code
 
curl https://api.payonify.com/v1/charges?last=10&before=cursor_def456 \
  -u "pk_test_abc123...:sk_test_xyz789..."

Pagination Best Practices

1. Use reasonable page sizes: Keep your limit parameter moderate (10-25) to avoid long response times.

2. Check for more pages: Always check the has_next_page field to determine if there are more results to fetch.

3. Store cursors: When implementing pagination in your application, store both the start_cursor and end_cursor to allow users to navigate forward and backward.

4. Handle empty pages: If your request returns an empty data array, it means there are no more objects to retrieve.

Iterating Through All Objects

To retrieve all objects, you can implement code similar to this (pseudocode):

Code
 
let allObjects = []
let cursor = null

do {
  const response = await fetchObjects(cursor)
  allObjects = allObjects.concat(response.data)
  cursor = response.paging.end_cursor
} while (response.paging.has_next_page)

Notes on Cursor Stability

• Cursors are opaque tokens and their format may change without notice
• Cursors typically expire after 24 hours
• New objects added to the collection may affect pagination

Tip: You can combine pagination with filtering to efficiently navigate through specific subsets of your data. For example, you could filter charges by status and date range while using pagination to move through the results.