Docs
Acessar painel

Saques

Simular um saque

POSThttps://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.

POST/v1/payouts/quote
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
}'
200Resposta
{
  "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ório

Valor que você pretende pedir, em centavos (inteiro ou string decimal).

Resposta 200

currencystring

Moeda (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_fundsbooleano

true quando o saldo disponível cobre o valor pedido.

limit_exceededstring ou null

Limite 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_centsstring

Limite por saque em vigor, em centavos.

manual_approvalbooleano

true 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

StatusCódigoQuando
401unauthorizedChave ausente, inválida, revogada ou expirada.
403forbiddenA chave não tem o escopo exigido (details.reason = "missing_scope").
409conflictA conta ainda não tem tarifa contratada vigente (details.reason = "no_pricing_policy"); fale com a Koku.
422validation_errorValor inválido ou menor ou igual à taxa de saque (details.reason = "amount_does_not_cover_fee").
429rate_limitedLimite de requisições excedido. Aguarde o tempo de Retry-After.
500internal_errorFalha inesperada. Repita com a mesma Idempotency-Key; persistindo, envie o correlation_id à Koku (veja Suporte).

Formato do corpo de erro em Erros.