Consultar extrato · Documentação Koku

GEThttps://api.kokupay.com/v1/statement

Lista os lançamentos que movimentaram o seu saldo. Cada venda traz bruto, tarifa e líquido; cada devolução ou contestação traz o caso e o pedido a que se refere.

GET/v1/statement

curl -X GET 'https://api.kokupay.com/v1/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100', {
  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/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100",
    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/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100');
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": [
    {
      "journal_id": "2b7e4c19-8a3d-4f60-9c15-e7a2d5b8f031",
      "line_no": 1,
      "event_type": "payout.paid",
      "description": "Saque pago (E98765432202610121300Sq4Ke7Mn2Pw)",
      "economic_at": "2026-10-12T13:00:00.000Z",
      "posted_at": "2026-10-12T13:04:00.000Z",
      "position": "payout_reserved",
      "amount_cents": "-5000",
      "source_type": "payout",
      "source_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
      "is_reversal": false,
      "sale": null,
      "payout": {
        "payout_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
        "requested_cents": "5000",
        "fee_cents": "500",
        "amount_cents": "4500"
      },
      "financial_case": null
    },
    {
      "journal_id": "6d0a3f58-2c9e-4b17-a4d6-1f8e5b3c7a29",
      "line_no": 2,
      "event_type": "payout.reserved",
      "description": "Reserva para saque solicitado",
      "economic_at": "2026-10-10T17:00:00.000Z",
      "posted_at": "2026-10-10T17:00:00.000Z",
      "position": "payout_reserved",
      "amount_cents": "5000",
      "source_type": "payout",
      "source_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
      "is_reversal": false,
      "sale": null,
      "payout": {
        "payout_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
        "requested_cents": "5000",
        "fee_cents": "500",
        "amount_cents": "4500"
      },
      "financial_case": null
    },
    {
      "journal_id": "6d0a3f58-2c9e-4b17-a4d6-1f8e5b3c7a29",
      "line_no": 1,
      "event_type": "payout.reserved",
      "description": "Reserva para saque solicitado",
      "economic_at": "2026-10-10T17:00:00.000Z",
      "posted_at": "2026-10-10T17:00:00.000Z",
      "position": "available",
      "amount_cents": "-5000",
      "source_type": "payout",
      "source_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
      "is_reversal": false,
      "sale": null,
      "payout": {
        "payout_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
        "requested_cents": "5000",
        "fee_cents": "500",
        "amount_cents": "4500"
      },
      "financial_case": null
    },
    {
      "journal_id": "5e9b3d71-c2a8-4f06-8d14-b7e0a6c3f952",
      "line_no": 1,
      "event_type": "gateway.external_payout",
      "description": "Repasse feito pela Koku (E98765432202610081000Zx9Yw8Vu7Ts)",
      "economic_at": "2026-10-08T10:00:00.000Z",
      "posted_at": "2026-10-08T10:05:00.000Z",
      "position": "available",
      "amount_cents": "-10670",
      "source_type": "gateway",
      "source_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
      "is_reversal": false,
      "sale": null,
      "payout": null,
      "financial_case": null
    },
    {
      "journal_id": "0c5e8a3f-7b21-4d96-a4e0-3f9b1d7c5e28",
      "line_no": 2,
      "event_type": "gateway.funds_available",
      "description": "Valor liquidado e conciliado disponível para repasse",
      "economic_at": "2026-10-08T08:00:00.000Z",
      "posted_at": "2026-10-08T08:00:02.000Z",
      "position": "available",
      "amount_cents": "15670",
      "source_type": "charge",
      "source_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
      "is_reversal": false,
      "sale": {
        "payment_id": "d7b3e9c2-5a14-4f6e-8b20-9c1e4a7d3f56",
        "charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
        "order_reference": "PEDIDO-1001",
        "classification": "primary",
        "end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
        "paid_at": "2026-10-07T15:32:10.000Z",
        "gross_cents": "15990",
        "fee_cents": "320",
        "net_cents": "15670",
        "reserve_cents": "0",
        "payable_cents": "15670"
      },
      "payout": null,
      "financial_case": null
    },
    {
      "journal_id": "7a1d4c9e-2f6b-4e83-9b05-c8e3a2f1d746",
      "line_no": 3,
      "event_type": "charge.paid",
      "description": "Pagamento confirmado do pedido PEDIDO-1001",
      "economic_at": "2026-10-07T15:32:10.000Z",
      "posted_at": "2026-10-07T15:32:11.000Z",
      "position": "pending",
      "amount_cents": "15670",
      "source_type": "charge",
      "source_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
      "is_reversal": false,
      "sale": {
        "payment_id": "d7b3e9c2-5a14-4f6e-8b20-9c1e4a7d3f56",
        "charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
        "order_reference": "PEDIDO-1001",
        "classification": "primary",
        "end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
        "paid_at": "2026-10-07T15:32:10.000Z",
        "gross_cents": "15990",
        "fee_cents": "320",
        "net_cents": "15670",
        "reserve_cents": "0",
        "payable_cents": "15670"
      },
      "payout": null,
      "financial_case": null
    }
  ],
  "next_cursor": null,
  "as_of": "2026-10-08T10:10:00.000Z"
}

Autenticação

Authorization: Bearer <sua chave de API>

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

Parâmetros de consulta

fromstring (data e hora)

Início do período (inclusivo, ISO-8601). Padrão: 30 dias antes de to.

tostring (data e hora)

Fim do período (exclusivo, ISO-8601). Padrão: agora.

cursorstring

Cursor devolvido em next_cursor da página anterior.

até 2000 caracteres

limitinteiro

Itens por página.

de 1 a 500

Resposta 200

itemslista de objetos

Lançamentos do período, do mais recente para o mais antigo.

items[].journal_idstring (uuid)

Identificador do lançamento contábil (vários itens podem compartilhar o mesmo).

items[].line_nointeiro

Linha dentro do lançamento.

items[].event_typestring

Fato que gerou o lançamento. Os mais comuns: charge.paid (venda paga), gateway.funds_available (venda liquidada e disponível), gateway.external_payout (repasse feito pela Koku para a sua conta bancária), case.hold e refund.completed (devolução). A lista completa está em Saldo e extrato.

items[].descriptionstring ou null

Descrição em texto fixo da Koku para o tipo de lançamento (ex.: Repasse feito pela Koku (E2E...)). Use event_type para decidir no código.

items[].economic_atstring (data e hora)

Data econômica do fato (é a data usada no filtro from/to).

items[].posted_atstring (data e hora)

Momento do registro.

items[].positionstring

Posição do saldo afetada: pending, available, contract_reserve, case_hold, payout_reserved ou receivable.

items[].amount_centsstring (centavos)

Efeito na posição, em centavos: positivo aumenta, negativo reduz.

items[].source_typestring ou null

Tipo do objeto de origem: charge (cobrança e venda), financial_case (caso), gateway (lançamento da conta como um todo, como o repasse feito pela Koku ou a compensação de valor devido; source_id é o id da sua conta), gateway_receivable ou payout. Use event_type para saber o que aconteceu.

items[].source_idstring ou null

Identificador do objeto de origem.

items[].is_reversalbooleano

true em estorno de lançamento.

items[].saleobjeto ou null

Venda a que o lançamento se refere (quando houver).

items[].sale.payment_idstring (uuid)

Identificador do pagamento.

items[].sale.charge_idstring (uuid)

Cobrança da venda.

items[].sale.order_referencestring

Seu identificador do pedido.

items[].sale.classificationstring

primary (venda) ou late (pagamento tardio).

items[].sale.end_to_end_idstring

Identificador fim a fim do Pix.

items[].sale.paid_atstring (data e hora)

Momento do pagamento.

items[].sale.gross_centsstring (centavos)

Valor bruto pago, em centavos.

items[].sale.fee_centsstring (centavos)

Tarifa da Koku, em centavos.

items[].sale.net_centsstring (centavos)

Líquido da venda (bruto − tarifa), em centavos.

items[].sale.reserve_centsstring (centavos)

Reserva contratual retida da venda, em centavos.

items[].sale.payable_centsstring (centavos)

Quanto da venda vai para o seu saldo (líquido − reserva), em centavos.

items[].payoutobjeto ou null

Saque pedido pelo painel: valor pedido, taxa de saque e valor enviado. null nos demais lançamentos.

items[].payout.payout_idstring (uuid)

Identificador do saque.

items[].payout.requested_centsstring (centavos)

Valor pedido, em centavos.

items[].payout.fee_centsstring (centavos)

Taxa de saque, em centavos.

items[].payout.amount_centsstring (centavos)

Valor enviado (pedido − taxa), em centavos.

items[].financial_caseobjeto ou null

Caso (devolução, contestação MED ou bloqueio) a que o lançamento se refere.

items[].financial_case.case_idstring (uuid)

Identificador do caso.

items[].financial_case.case_typestring

Tipo do caso.

items[].financial_case.reasonstring ou null

Código do motivo (duplicate_payment, unmatched_payment, late_payment_review) ou null.

items[].financial_case.charge_idstring (uuid) ou null

Cobrança do caso.

items[].financial_case.order_referencestring ou null

Seu identificador do pedido.

next_cursorstring ou null

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

as_ofstring (data e hora)

Momento da leitura.

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`	Parâmetro inválido (`details.fields` indica qual).
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