Saldo e extrato · Documentação Koku

Saldo

GET /v1/balance mostra a sua posição na Koku. Escopo: balance:read. Referência: Consultar saldo.

GET/v1/balance

curl -X GET 'https://api.kokupay.com/v1/balance' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/balance', {
  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/balance",
    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/balance');
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

{
  "currency": "BRL",
  "pending_cents": "0",
  "available_cents": "15670",
  "contract_reserve_cents": "0",
  "blocked_cents": "0",
  "payout_reserved_cents": "0",
  "total_cents": "15670",
  "owed_to_koku_cents": "0",
  "payouts_suspended": false,
  "suspension_reasons": [],
  "payouts_by_koku": true,
  "payouts_by_koku_message": "Os repasses são feitos pela Koku",
  "available_for_payout_cents": "0",
  "to_receive_cents": "15670",
  "as_of": "2026-10-08T09:00:00.000Z"
}

Campo	Significado
`pending_cents`	Líquido de vendas pagas que ainda não foram liquidadas e conciliadas.
`available_cents`	Liquidado e conciliado: pronto para o repasse.
`contract_reserve_cents`	Reserva contratual. Continua sendo seu e é liberada conforme o contrato.
`blocked_cents`	Bloqueado por devolução em andamento, contestação (MED) ou pagamento retido.
`payout_reserved_cents`	Reservado para repasses em andamento.
`to_receive_cents`	A receber da Koku: pendente + disponível + reserva contratual (sem o bloqueado).
`owed_to_koku_cents`	Valor devido à Koku (por exemplo, uma contestação maior que o saldo). É abatido do que ficar disponível em seguida.
`payouts_by_koku`	`true` quando os repasses são feitos pela Koku conforme o contrato.
`payouts_suspended`	`true` quando os repasses estão suspensos; o motivo vem em `suspension_reasons`.

Os valores vêm em centavos (string). Pago não é liquidado, e liquidado não é disponível: veja Como funciona. O evento balance.available avisa quando um valor passa a disponível.

Extrato

GET /v1/statement lista os lançamentos que movimentaram o seu saldo, do mais recente para o mais antigo. Escopo: statement:read. Referência: Consultar extrato.

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": "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": "-15670",
      "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"
}

Como ler cada item:

position diz qual parte do saldo mudou (pending, available, contract_reserve, case_hold, payout_reserved ou receivable) e amount_cents o efeito: positivo aumenta, negativo reduz. Uma venda que passa de pendente para disponível gera duas linhas no mesmo lançamento (journal_id): uma negativa em pending e uma positiva em available.
sale liga a linha à venda: pedido, bruto (gross_cents), tarifa (fee_cents), líquido (net_cents), reserva e o que vai para o saldo (payable_cents).
financial_case liga a linha a uma devolução, contestação ou bloqueio, com o pedido a que se refere.
event_type diz o que gerou o lançamento e é o campo para decidir no código. description é um texto fixo da Koku para exibição.
O período usa economic_at (data do fato): from inclusivo, to exclusivo. Padrão: os últimos 30 dias.
Até 500 itens por página; pagine com cursor. Veja Paginação.

Tipos de lançamento

`event_type`	O que é	`position`
`charge.paid`	Venda paga: o líquido entra como pendente.	`pending`
`reserve.held` / `reserve.released`	Reserva contratual da venda retida e, depois, liberada.	`contract_reserve`, `pending` ou `available`
`gateway.funds_available`	Venda liquidada e conciliada: sai de pendente e entra em disponível.	`pending` e `available`
`gateway.external_payout`	Repasse feito pela Koku para a sua conta bancária (`source_type: "gateway"`, `source_id` = id da sua conta). `description` traz a referência da transferência, a mesma de Listar repasses.	`available` (negativo)
`charge.payment_held`	Pagamento duplicado ou sem correspondência, retido para devolução ao pagador.	`case_hold`
`case.hold` / `case.release`	Valor bloqueado por devolução ou contestação e, se for o caso, liberado.	`pending`, `available` e `case_hold`
`refund.completed` / `case.returned`	Devolução concluída: o valor bloqueado saiu para o pagador.	`case_hold`
`gateway.receivable_covered`	Valor devido à Koku compensado com saldo disponível.	`available` e `receivable`
`journal.reversal`	Estorno de um lançamento anterior (`is_reversal: true`).	a do lançamento estornado

Tipos novos podem aparecer: trate um event_type desconhecido pelo sinal de amount_cents e pela position.

Repasses feitos pela Koku

Os repasses do seu saldo para a sua conta bancária são feitos pela Koku, conforme o contrato. Você não precisa pedir saque pela API: a Koku transfere e registra cada repasse, que já sai do seu saldo disponível. Por isso o saldo traz payouts_by_koku: true e available_for_payout_cents: "0".

GET /v1/payouts/by-koku lista os repasses feitos, com a referência da transferência. Escopo: payouts:read. Referência: Listar repasses.

GET/v1/payouts/by-koku

curl -X GET 'https://api.kokupay.com/v1/payouts/by-koku' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/payouts/by-koku', {
  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/payouts/by-koku",
    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/payouts/by-koku');
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": "4b8f2c6e-1a9d-4e37-8c05-6f3a9d2e7b14",
      "amount_cents": "15670",
      "external_reference": "E98765432202610081000Zx9Yw8Vu7Ts",
      "paid_at": "2026-10-08T10:00:00.000Z"
    }
  ]
}

Conciliação

Para fechar o seu financeiro:

Some as vendas do período pelo extrato (sale.gross_cents, sale.fee_cents, sale.net_cents) ou pelas cobranças pagas.
Desconte devoluções e contestações (financial_case).
Compare o disponível com os repasses: cada linha gateway.external_payout do extrato corresponde a um item de Listar repasses com a mesma referência de transferência.

Tarifas por venda: veja Tarifas.

#Saldo

#Extrato

#Tipos de lançamento

#Repasses feitos pela Koku

#Conciliação

Saldo

Extrato

Tipos de lançamento

Repasses feitos pela Koku

Conciliação