Saques
Simular um saque
https://api.kokupay.com/v1/payouts/quote Calcula, sem reservar nada, a taxa de saque e o valor que chegaria à conta para um valor pedido, e diz se o saldo disponível cobre o pedido e se algum limite seria ultrapassado. Use antes de Pedir um saque para mostrar a prévia ao seu financeiro.
curl -X POST 'https://api.kokupay.com/v1/payouts/quote' \
-H "Authorization: Bearer $KOKU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 5000
}'const response = await fetch('https://api.kokupay.com/v1/payouts/quote', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount_cents: 5000,
}),
});
const data = await response.json();
console.log(response.status, data);import os
import requests
response = requests.request(
"POST",
"https://api.kokupay.com/v1/payouts/quote",
headers={
"Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
},
json={
"amount_cents": 5000,
},
timeout=30,
)
print(response.status_code, response.json())<?php
$ch = curl_init('https://api.kokupay.com/v1/payouts/quote');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount_cents' => 5000,
]),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);{
"currency": "BRL",
"requested_cents": "5000",
"fee_cents": "500",
"net_cents": "4500",
"available_cents": "15670",
"sufficient_funds": true,
"limit_exceeded": null,
"per_payout_max_cents": "1500000",
"manual_approval": true,
"quoted_at": "2026-10-10T16:59:00.000Z"
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: payouts:read. Veja Chaves de API.
Corpo da requisição
JSON (Content-Type: application/json). Campos não listados são recusados com 422.
amount_centsinteiro ou stringobrigatórioValor que você pretende pedir, em centavos (inteiro ou string decimal).
Resposta 200
currencystringMoeda (BRL).
Valores: BRL
requested_centsstring (centavos)Valor pedido, em centavos.
fee_centsstring (centavos)Taxa de saque que seria descontada, em centavos.
net_centsstring (centavos)Valor que chegaria à conta (pedido − taxa), em centavos.
available_centsstring (centavos)Saldo disponível para saque no momento da simulação, em centavos.
sufficient_fundsbooleanotrue quando o saldo disponível cobre o valor pedido.
limit_exceededstring ou nullLimite que o pedido ultrapassaria e que faria a Koku recusá-lo com 422: per_payout, daily ou monthly. null quando cabe nos limites.
per_payout_max_centsstringLimite por saque em vigor, em centavos.
manual_approvalbooleanotrue quando o pedido aguardaria a análise de uma pessoa da Koku (sempre, para a chave de API).
quoted_atstring (data e hora)Momento da simulação.
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"). |
| 409 | conflict | A conta ainda não tem tarifa contratada vigente (details.reason = "no_pricing_policy"); fale com a Koku. |
| 422 | validation_error | Valor inválido ou menor ou igual à taxa de saque (details.reason = "amount_does_not_cover_fee"). |
| 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.