Paginar os resultados

Vários endpoints da API do Payments Direct retornam resultados paginados quando uma lista pode conter muitos registros. A API usa dois estilos de paginação, conforme o endpoint:

• Paginação baseada em token para identidades, instrumentos financeiros e busca de pagamentos. A resposta inclui um valor opaco de nextToken que você informa para recuperar a próxima página.
• Paginação por offset para transações de ledger. Você especifica o índice do registro inicial (offset) e o número de registros a retornar (page-size).

A tabela abaixo resume qual estilo se aplica a cada endpoint paginado.

A paginação baseada em token usa um token de string opaco para marcar a sua posição em um conjunto de resultados. Quando a API retorna um nextToken na resposta, há mais resultados disponíveis. Quando o nextToken está ausente, você chegou à última página.

Os tokens são opacos e podem mudar entre releases. Não tente decodificar, interpretar nem construir valores de token.

Em GET /v3/identities e GET /v3/identities/{identity-id}/financial-instruments, informe os parâmetros de paginação como parâmetros de consulta.

Parâmetros da requisição:

Exemplo: primeira página

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

Exemplo de resposta (há mais páginas disponíveis):

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

Exemplo: página seguinte

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

Quando a resposta não inclui o campo nextToken, você já recuperou todos os registros disponíveis.

O endpoint POST /v3/payments/filter usa paginação baseada em token, mas os parâmetros de paginação são informados no corpo da requisição, e não como parâmetros de consulta.

Campos de paginação do corpo da requisição:

Exemplo: primeira página

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
    }
  }'

Exemplo de resposta (há mais páginas disponíveis):

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

Exemplo: página seguinte

Inclua o valor de lastPageToken da resposta anterior no corpo da próxima requisição:

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

Quando a resposta não inclui o campo page.lastPageToken, você já recuperou todos os pagamentos correspondentes.

O endpoint GET /v2/ledger-transactions usa paginação por offset. Você controla a janela de resultados com dois parâmetros: page-size (quantos registros retornar) e offset (quantos registros pular).

Parâmetros da requisição:

A resposta inclui um campo total com a contagem geral de registros correspondentes. Use total, pageSize e pageElements para determinar se existem páginas adicionais.

Campos da resposta:

Exemplo: primeira página

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>"

Exemplo de resposta:

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

Exemplo: segunda página

Com total=83 e pageSize=25, a segunda página começa em 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>"

Você recuperou todos os registros quando offset + pageElements >= total.

Use o tamanho máximo de página em recuperações em massa. Quando o seu objetivo é recuperar todos os registros (por exemplo, para conciliação), defina limit ou page-size no valor máximo permitido para reduzir o número de requisições.

Verifique a ausência do nextToken, não o valor dele. Nos endpoints baseados em token, o sinal correto de que você chegou à última página é a ausência de nextToken (ou de page.lastPageToken) na resposta, e não um valor de token específico.

Não modifique nem construa tokens. Os tokens são opacos. Uma lógica que interprete ou concatene valores de token vai quebrar quando o formato do token mudar.

Considere os registros adicionados durante a recuperação. A paginação por offset sobre um conjunto de resultados que muda ativamente pode gerar lacunas ou duplicatas. Em transações de ledger, use um intervalo de tempo fixo (start-dttm e end-dttm) para garantir que o conjunto de resultados não mude enquanto você pagina por ele.

Não armazene tokens em cache entre sessões. Os tokens são válidos apenas na sessão em que foram emitidos. Sempre inicie uma nova sequência de paginação para cada novo trabalho de recuperação.