Toutes les listes se parcourent au curseur par défaut. Plus stable que l’offset : pas de saut si la collection mute pendant la pagination.

Format

Requête :
Réponse — un tableau, sans enveloppe :
  • take : taille de page. Défaut 20, plafonnée silencieusement à 100 (jusqu’à 500 pour les payouts, settlements, dépôts et transactions wallet) ; une valeur supérieure n’est pas rejetée, elle est ramenée au plafond.
  • cursor : l’id du dernier élément de la page précédente. Omettez-le pour la première page.
  • Fin de collection : la page renvoyée est plus courte que take, ou vide.
Une seule exception : GET /v1/webhook-endpoints/deliveries renvoie {"items": [...], "nextCursor": …} et attend limit plutôt que take.

Pagination par page (offset)

Certaines listes acceptent aussi page (1-based), utile pour un tableau paginé côté interface. Le total est alors renvoyé dans l’en-tête X-Total-Count :
Disponible sur /v1/payouts, /v1/settlements, /v1/payments/payins et /v1/accounts/transactions. Pour un export exhaustif, préférez le curseur : l’offset peut sauter ou répéter un enregistrement si la collection bouge entre deux pages.

Avec le SDK

Lecture page par page

Le SDK Node normalise la réponse en { data, nextCursor } et reconstitue le curseur pour vous :
En PHP et en Python, list() renvoie le tableau tel quel — utilisez iterate pour ne pas gérer le curseur à la main.

Async iterator (recommandé)

L’iterator gère le curseur tout seul et s’arrête en fin de collection. Disponible sur toutes les ressources paginées : paymentIntents, payouts, payins, invoices, products, settlements, whitelistAddresses, et les transactions wallet.

Filtres

Liste-spécifiques (voir la référence API par endpoint) :
  • Payment Intents : status, assetCode, source, from, to
  • Payouts : status, assetCode, payoutType
  • Invoices : status, from, to
  • Products : isActive

Ordre

Par défaut : createdAt DESC (plus récent d’abord).

Limites de profondeur

Pas de limite hard sur la profondeur de pagination : vous pouvez itérer sur des millions de payment intents. Mais préférez les filtres de date :
Le cursor est opaque : ne le parsez pas. Sa structure peut changer sans préavis. Conservez-le tel quel et renvoyez-le.