Listar cobranças · Documentação Koku

GEThttps://api.kokupay.com/v1/pix/charges

Lista as cobranças da conta, das mais recentes para as mais antigas, com filtros e paginação por cursor.

GET/v1/pix/charges

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

const response = await fetch('https://api.kokupay.com/v1/pix/charges?status=paid&limit=50', {
  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?status=paid&limit=50",
    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?status=paid&limit=50');
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": null
}

Autenticação

Authorization: Bearer <sua chave de API>

Escopo exigido: charges:read. Veja Chaves de API.

Parâmetros de consulta

statusstring

Filtra pelo estado da cobrança.

Valores: created, pending, paid, partially_refunded, refunded, expired, cancelled, failed

order_referencestring

Filtra pelo seu identificador do pedido (valor exato).

até 120 caracteres

created_fromstring (data e hora)

Criadas a partir deste instante (inclusivo, ISO-8601).

created_tostring (data e hora)

Criadas antes deste instante (exclusivo, ISO-8601).

qstring

Busca por referência do pedido, id da cobrança, txid, E2E, nome ou documento do pagador.

1 a 120 caracteres

cursorstring

Cursor devolvido em next_cursor da página anterior.

até 2000 caracteres

limitinteiro

Itens por página.

de 1 a 200

Resposta 200

itemslista de objetos

Itens da página.

items[].idstring (uuid)

Identificador da cobrança na Koku.

items[].gateway_idstring (uuid)

Identificador da sua conta na Koku.

items[].environmentstring

Ambiente da cobrança: production (sandbox está reservado para o ambiente de testes, em preparação).

Valores: sandbox, production

items[].order_referencestring

Identificador do pedido enviado por você.

items[].amount_centsstring (centavos)

Valor bruto da cobrança, em centavos (string decimal: "15990" = R$ 159,90).

items[].currencystring

Moeda (BRL).

Valores: BRL

items[].descriptionstring ou null

Descrição enviada na criação.

items[].statusstring

Estado da cobrança. Veja Estados da cobrança.

Valores: created, pending, paid, partially_refunded, refunded, expired, cancelled, failed

items[].fee_percent_bpsinteiro

Parte percentual da tarifa vigente na criação, em pontos-base (200 = 2,00%).

items[].fee_fixed_centsstring (centavos)

Parte fixa da tarifa por transação, em centavos.

items[].fee_centsstring (centavos) ou null

Tarifa da Koku sobre a venda, em centavos. null até o pagamento.

items[].net_centsstring (centavos) ou null

Valor líquido da venda (bruto − tarifa), em centavos. null até o pagamento.

items[].reserve_centsstring (centavos) ou null

Parte do líquido retida como reserva contratual, em centavos. null até o pagamento.

items[].refunded_centsstring (centavos)

Total já devolvido ao pagador, em centavos.

items[].expires_atstring (data e hora) ou null

Fim da validade do QR.

items[].paid_atstring (data e hora) ou null

Momento do pagamento confirmado.

items[].late_paymentbooleano

true quando o pagamento chegou depois da expiração (pagamento tardio).

items[].is_simulatedbooleano

false em produção. true fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real.

items[].created_atstring (data e hora)

Criação da cobrança.

items[].updated_atstring (data e hora)

Última alteração.

items[].pixobjeto ou null

QR vigente. null enquanto a emissão não terminou ou quando a cobrança foi recusada.

items[].pix.qr_code_payloadstring ou null

Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele.

items[].pix.txidstring ou null

Identificador da transação Pix.

items[].pix.expires_atstring (data e hora) ou null

Fim da validade deste QR.

items[].end_to_end_idstring ou null

Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga.

items[].payments_countinteiro

Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados).

items[].failure_messagestring ou null

Quando status é failed: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: Emissão recusada pela análise de risco.). Os textos possíveis estão em Estados da cobrança. null nos demais estados.

next_cursorstring ou null

Cursor da próxima página; null quando não há mais itens.

Erros

Status	Código	Quando
401	`unauthorized`	Chave ausente, inválida, revogada ou expirada.
403	`forbidden`	A chave não tem o escopo exigido (`details.reason = "missing_scope"`).
422	`validation_error`	Filtro inválido ou cursor adulterado.
429	`rate_limited`	Limite de requisições excedido. Aguarde o tempo de `Retry-After`.
500	`internal_error`	Falha inesperada. Repita com a mesma `Idempotency-Key`; persistindo, envie o `correlation_id` à Koku (veja Suporte).

Formato do corpo de erro em Erros.

#Autenticação

#Parâmetros de consulta

#Resposta 200

#Erros

Autenticação

Parâmetros de consulta

Resposta 200

Erros