Saques

Os repasses do seu saldo para a conta bancária da sua empresa são feitos pela Koku, conforme o contrato. Você pede o saque a qualquer hora, inclusive em fins de semana e feriados, pelo painel ou pela API; a Koku analisa cada pedido, transfere e marca o saque como pago.

#O que acontece com um pedido

1. O valor pedido sai do disponível na hora e fica reservado (payout_reserved_cents no saldo; lançamento payout.reserved no extrato). Enquanto reservado, ele não pode ser usado em outro saque.
2. A taxa de saque do seu contrato é descontada do valor pedido. Exemplo: pedido de R$ 50,00 com taxa de R$ 5,00 = R$ 45,00 enviados. A resposta de cada saque mostra os três valores: requested_cents (pedido), fee_cents (taxa) e amount_cents (o que chega à conta).
3. A Koku analisa o pedido. Todo saque pedido pela API aguarda a aprovação de uma pessoa da Koku (approval_status = "pending"). Enquanto aguarda, você pode cancelá-lo.
4. Aprovado, a Koku faz a transferência para a conta de destino e marca o saque como pago, com a referência da transferência (transfer_reference; lançamento payout.paid no extrato).
5. Recusado ou cancelado, o valor volta ao disponível (lançamento payout.released) e o motivo da recusa aparece em approval_reason.

Quando o dinheiro chega. Cada adquirente que processa as suas vendas paga a Koku em um horário próprio (algumas na hora, outras em dia útil e horário comercial). Um pedido feito fora do horário da adquirente pode ser recusado pela Koku: nesse caso, o valor volta ao disponível e basta pedir de novo no próximo horário. No painel, a tela Saques mostra as adquirentes liberadas para a sua empresa e o aviso de cada uma.

#Conta de destino

Só contas da mesma titularidade da sua empresa, verificadas pela Koku, recebem saque. O cadastro é feito pelo painel, em Configurações → Dados bancários; a Koku confere a titularidade e a conta passa a verified. Pela API, Listar contas de destino devolve as contas cadastradas (com os dados mascarados) e o id que você usa no pedido.

#Limites

• Até R$ 15.000,00 por saque. Para valores maiores, faça mais de um pedido, quantos o seu saldo permitir.
• Limites do seu contrato, quando existem (por saque, por dia e por mês), valem para o valor pedido. Consultar as condições de saque mostra o limite em vigor e quanto já foi pedido hoje e no mês; Simular um saque diz antes se um valor passaria de algum limite.
• O valor pedido precisa ser maior que a taxa de saque (minimum_request_cents nas condições de saque).

#Pedir pela API

Escopos: payouts:write para pedir e cancelar, payouts:read para consultar, beneficiaries:read para listar as contas de destino. Veja Chaves de API.

POST /v1/payouts
Authorization: Bearer koku_live_3f9a1c2b4d5e_<segredo>
Idempotency-Key: saque-2026-10-10-01
Content-Type: application/json

{ "amount_cents": 5000, "beneficiary_account_id": "e7a2c5f1-3b8d-4e60-a9c4-1f5b7d3e9a28" }

A resposta 201 traz o saque com approval_status = "pending" e execution_status = "reserved". Use uma Idempotency-Key única por pedido: repetir a mesma chave com o mesmo corpo devolve o mesmo saque (200 com Idempotent-Replayed: true), sem reservar de novo. Referência: Pedir um saque.

Antes de pedir, Simular um saque devolve a taxa, o valor que chegaria à conta e se o saldo cobre o pedido, sem reservar nada.

#Acompanhar

• Por consulta: Consultar um saque e Listar saques. approval_status diz como está a análise (pending, approved, rejected); execution_status diz como está a transferência (reserved, queued, paid, cancelled).
• Por webhook: payout.created, payout.approved, payout.rejected, payout.paid e, se você cancelar, payout.failed. Veja Eventos.
• No extrato: payout.reserved, payout.paid e payout.released. Veja Tipos de lançamento.

#Cancelar

Enquanto o saque aguarda a análise, Cancelar um saque devolve o valor pedido ao disponível na hora. Depois de aprovado, o saque está com a Koku para transferência e não pode mais ser cancelado.

#Pedir pelo painel

No painel, em Saques → Solicitar saque: informe o valor, escolha a conta de destino, confira a taxa e o valor que chega, e confirme com a verificação em duas etapas. O pedido segue o mesmo caminho descrito acima.

#Repasses sem pedido

A Koku também pode repassar valores sem que você peça, conforme o contrato. Cada repasse sai do disponível e aparece no extrato como gateway.external_payout; a lista está em Listar repasses feitos pela Koku.