Paginação · Documentação Koku

As listas da API usam cursor: cada página traz next_cursor, um texto opaco que aponta para a próxima. Quando next_cursor vem null, acabou.

Parâmetro	Descrição
`limit`	Itens por página: de 1 a 200 (até 500 no extrato).
`cursor`	O `next_cursor` da página anterior. Omitido = primeira página.

Exemplo

Primeira página:

GET/v1/pix/charges

curl -X GET 'https://api.kokupay.com/v1/pix/charges?limit=1' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/pix/charges?limit=1', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.kokupay.com/v1/pix/charges?limit=1",
    headers={
        "Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.kokupay.com/v1/pix/charges?limit=1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

200Resposta

{
  "items": [
    {
      "id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
      "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
      "environment": "production",
      "order_reference": "PEDIDO-1001",
      "amount_cents": "15990",
      "currency": "BRL",
      "description": "Pedido 1001 - Loja Exemplo",
      "status": "paid",
      "fee_percent_bps": 200,
      "fee_fixed_cents": "0",
      "fee_cents": "320",
      "net_cents": "15670",
      "reserve_cents": "0",
      "refunded_cents": "0",
      "expires_at": "2026-10-07T16:00:00.000Z",
      "paid_at": "2026-10-07T15:32:10.000Z",
      "late_payment": false,
      "is_simulated": false,
      "created_at": "2026-10-07T15:30:00.000Z",
      "updated_at": "2026-10-07T15:32:11.000Z",
      "pix": {
        "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/8d3f6a124b9e4c71a2d56e0f1b3c9a475204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
        "txid": "8d3f6a124b9e4c71a2d56e0f1b3c9a47",
        "expires_at": "2026-10-07T16:00:00.000Z"
      },
      "end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
      "payments_count": 1,
      "failure_message": null
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wN1QxNTozMDowMC4wMDAwMDBaIiwiaWQiOiI4ZDNmNmExMiJ9"
}

Próxima página, com o cursor recebido:

GET/v1/pix/charges

curl -X GET 'https://api.kokupay.com/v1/pix/charges?limit=1&cursor=eyJ0IjoiMjAyNi0xMC0wN1QxNTozMDowMC4wMDAwMDBaIiwiaWQiOiI4ZDNmNmExMiJ9' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/pix/charges?limit=1&cursor=eyJ0IjoiMjAyNi0xMC0wN1QxNTozMDowMC4wMDAwMDBaIiwiaWQiOiI4ZDNmNmExMiJ9', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.kokupay.com/v1/pix/charges?limit=1&cursor=eyJ0IjoiMjAyNi0xMC0wN1QxNTozMDowMC4wMDAwMDBaIiwiaWQiOiI4ZDNmNmExMiJ9",
    headers={
        "Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.kokupay.com/v1/pix/charges?limit=1&cursor=eyJ0IjoiMjAyNi0xMC0wN1QxNTozMDowMC4wMDAwMDBaIiwiaWQiOiI4ZDNmNmExMiJ9');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

200Resposta

{
  "items": [
    {
      "id": "b2e7c4d1-9a36-4f58-8c0e-1d5a7f3b6e92",
      "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
      "environment": "production",
      "order_reference": "PEDIDO-1002",
      "amount_cents": "15990",
      "currency": "BRL",
      "description": "Pedido 1002 - Loja Exemplo",
      "status": "expired",
      "fee_percent_bps": 200,
      "fee_fixed_cents": "0",
      "fee_cents": null,
      "net_cents": null,
      "reserve_cents": null,
      "refunded_cents": "0",
      "expires_at": "2026-10-07T16:00:00.000Z",
      "paid_at": null,
      "late_payment": false,
      "is_simulated": false,
      "created_at": "2026-10-07T15:30:00.000Z",
      "updated_at": "2026-10-07T16:00:05.000Z",
      "pix": {
        "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/b2e7c4d19a364f588c0e1d5a7f3b6e925204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
        "txid": "b2e7c4d19a364f588c0e1d5a7f3b6e92",
        "expires_at": "2026-10-07T16:00:00.000Z"
      },
      "end_to_end_id": null,
      "payments_count": 0,
      "failure_message": null
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wN1QxNToyOTowMC4wMDAwMDBaIiwiaWQiOiJiMmU3YzRkMSJ9"
}

Regras

Mantenha os mesmos filtros em todas as páginas; troque só o cursor.
Não monte nem altere o cursor: ele é opaco. Cursor adulterado responde 422.
As listas vêm da mais recente para a mais antiga. Itens criados depois da primeira página aparecem numa nova consulta, não no meio da paginação.
Paginam por cursor: Listar cobranças, Consultar extrato, Listar eventos e Listar entregas.

#Exemplo

#Regras

Exemplo

Regras