Saldo e extrato
Consultar saldo
https://api.kokupay.com/v1/balance Mostra a sua posição na Koku: o que está pendente de liquidação, o que já está disponível, reservas, bloqueios e quanto você tem a receber.
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);{
"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: peça o saque pelo painel, a qualquer hora",
"available_for_payout_cents": "15670",
"to_receive_cents": "15670",
"as_of": "2026-10-08T09:00:00.000Z"
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: balance:read. Veja Chaves de API.
Resposta 200
currencystringMoeda (BRL).
Valores: BRL
pending_centsstring (centavos)Vendas pagas, ainda não liquidadas e conciliadas, em centavos.
available_centsstring (centavos)Vendas liquidadas e conciliadas, prontas para repasse, em centavos.
contract_reserve_centsstring (centavos)Reserva contratual (continua sendo sua; é liberada conforme o contrato), em centavos.
blocked_centsstring (centavos)Bloqueado por devolução, contestação ou pagamento retido, em centavos.
payout_reserved_centsstring (centavos)Reservado para saques pedidos e ainda não pagos, em centavos.
total_centsstring (centavos)Soma das posições acima, em centavos.
owed_to_koku_centsstring (centavos)Valor devido à Koku (por exemplo, devolução maior que o saldo), em centavos.
payouts_suspendedbooleanotrue quando os repasses estão suspensos (veja suspension_reasons).
suspension_reasonslista de stringMotivos da suspensão dos repasses.
payouts_by_kokubooleanotrue quando os repasses são feitos pela Koku conforme o contrato: você pede o saque pelo painel, a qualquer hora, e a Koku aprova e transfere.
payouts_by_koku_messagestring ou nullMensagem para exibir quando os repasses são feitos pela Koku.
available_for_payout_centsstring (centavos)Quanto você pode pedir de saque agora pelo painel (o disponível), em centavos.
to_receive_centsstring (centavos)Total a receber da Koku: pendente + disponível + reserva contratual (sem o bloqueado), em centavos.
as_ofstring (data e hora)Momento da leitura do saldo.
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"). |
| 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.