Pagination

Overview

All Xtopay list endpoints use cursor-based pagination. Unlike page-number pagination, cursors remain stable as new records are inserted — you won't skip or see duplicate records while paginating.

Request parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Number of records to return (max `100`)
`after`	string	—	Return records after this cursor (next page)
`before`	string	—	Return records before this cursor (previous page)

Response shape

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "cur_a1b2c3d4",
    "previous_cursor": null,
    "total_count": 247
  }
}

Example

// First page
const page1 = await xtopay.payments.list({ limit: 20 });

// Next page
if (page1.pagination.has_more) {
  const page2 = await xtopay.payments.list({
    limit: 20,
    after: page1.pagination.next_cursor,
  });
}

Auto-pagination

The SDK provides an async iterator that handles cursors automatically:

for await (const payment of xtopay.payments.listAutoPaging({ limit: 50 })) {
  console.log(payment.id, payment.amount);
}

Filtering

List endpoints accept filter query parameters alongside pagination:

const payments = await xtopay.payments.list({
  limit: 20,
  status: "succeeded",
  currency: "GHS",
  created_after: "2026-01-01T00:00:00Z",
  created_before: "2026-02-01T00:00:00Z",
});