Cancelar um saque · Documentação Koku

POSThttps://api.kokupay.com/v1/payouts/{id}/cancel

Cancela um saque que ainda aguarda a análise da Koku: o valor pedido volta ao saldo disponível na hora (lançamento payout.released) e o evento payout.failed é enviado com o motivo que você informou. Depois de aprovado, o saque está com a Koku para transferência e não pode mais ser cancelado.

POST/v1/payouts/{id}/cancel

curl -X POST 'https://api.kokupay.com/v1/payouts/d0b4f8a2-6c1e-4f7b-9a35-2e8c5d1f7b46/cancel' \
  -H "Authorization: Bearer $KOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Pedido feito por engano"
}'

const response = await fetch('https://api.kokupay.com/v1/payouts/d0b4f8a2-6c1e-4f7b-9a35-2e8c5d1f7b46/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reason: 'Pedido feito por engano',
  }),
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "POST",
    "https://api.kokupay.com/v1/payouts/d0b4f8a2-6c1e-4f7b-9a35-2e8c5d1f7b46/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
    },
    json={
        "reason": "Pedido feito por engano",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.kokupay.com/v1/payouts/d0b4f8a2-6c1e-4f7b-9a35-2e8c5d1f7b46/cancel');
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([
        'reason' => 'Pedido feito por engano',
    ]),
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

200Resposta

{
  "id": "d0b4f8a2-6c1e-4f7b-9a35-2e8c5d1f7b46",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "requested_cents": "1000",
  "fee_cents": "500",
  "amount_cents": "500",
  "currency": "BRL",
  "beneficiary_account_id": "e7a2c5f1-3b8d-4e60-a9c4-1f5b7d3e9a28",
  "destination": {
    "holder_name": "Loja Exemplo Ltda",
    "holder_document_masked": "**********0001",
    "pix_key_masked": "**********0001",
    "bank_ispb": null
  },
  "approval_status": "pending",
  "approval_mode": null,
  "approval_reason": null,
  "approval_decided_at": null,
  "execution_status": "cancelled",
  "scheduled_for": null,
  "submitted_at": null,
  "confirmed_at": null,
  "end_to_end_id": null,
  "failure_reason": "Pedido feito por engano",
  "awaiting_second_approval": false,
  "waiting_reason": null,
  "next_attempt_at": null,
  "execution_channel": "manual_transfer",
  "transfer_reference": null,
  "created_at": "2026-10-13T09:30:00.000Z"
}

Autenticação

Authorization: Bearer <sua chave de API>

Escopo exigido: payouts:write. Veja Chaves de API.

Parâmetros de caminho

idstring (uuid)obrigatório

Identificador do saque que aguarda análise.

Corpo da requisição

JSON (Content-Type: application/json). Campos não listados são recusados com 422.

reasonstring

Motivo do cancelamento, para o seu controle (até 500 caracteres). Opcional.

até 500 caracteres

Resposta 200

idstring (uuid)

Identificador do saque.

gateway_idstring (uuid)

Identificador da sua conta na Koku.

environmentstring

Ambiente: production (sandbox está reservado para o ambiente de testes, em preparação).

Valores: sandbox, production

requested_centsstring (centavos)

Valor pedido, em centavos. É o que saiu do saldo disponível.

fee_centsstring (centavos)

Taxa de saque descontada do valor pedido, em centavos.

amount_centsstring (centavos)

Valor enviado à conta de destino (pedido − taxa), em centavos.

currencystring

Moeda (BRL).

Valores: BRL

beneficiary_account_idstring (uuid)

Conta de destino do saque.

destinationobjeto

Dados da conta de destino no momento do pedido (mudar o cadastro depois não altera o saque).

destination.holder_namestring

Nome do titular da conta de destino.

destination.holder_document_maskedstring

CNPJ do titular, mascarado.

destination.pix_key_maskedstring ou null

Chave Pix de destino, mascarada; null quando a conta não tem chave Pix cadastrada.

destination.bank_ispbstring ou null

Código ISPB do banco de destino; null quando a conta não tem dados bancários cadastrados.

approval_statusstring

Análise da Koku: pending (aguardando), approved ou rejected. Um saque que você cancelou antes da análise continua pending aqui: use execution_status = "cancelled" para saber que ele foi encerrado.

approval_modestring ou null

Como foi decidido: manual (uma pessoa da Koku) ou automatic. null enquanto pendente.

approval_reasonstring ou null

Observação da Koku na decisão (por exemplo, o motivo da recusa). null enquanto pendente.

approval_decided_atstring (data e hora) ou null

Momento da decisão. null enquanto pendente.

execution_statusstring

Situação da transferência: reserved (valor reservado, aguardando a análise), queued (aprovado, aguardando a transferência da Koku), submitted, processing, unknown, paid, failed ou cancelled (recusado ou cancelado: o valor voltou ao disponível).

scheduled_forstring (data e hora) ou null

Quando o envio está agendado, se houver agendamento. null nos saques pagos por transferência da Koku.

submitted_atstring (data e hora) ou null

Momento em que o envio automático foi encaminhado, quando houver. null nos saques pagos por transferência da Koku.

confirmed_atstring (data e hora) ou null

Momento em que o saque foi pago.

end_to_end_idstring ou null

Identificador fim a fim do Pix, quando o envio é automático. Nos saques pagos por transferência da Koku, use transfer_reference.

failure_reasonstring ou null

Por que o saque foi encerrado sem pagamento: o motivo que você informou ao cancelar (ou um texto padrão), o motivo da recusa da Koku ou, no envio automático, um texto fixo da Koku. null enquanto o saque segue em andamento ou foi pago.

awaiting_second_approvalbooleano

true quando o valor exige uma segunda aprovação na Koku e a primeira já foi dada.

waiting_reasonstring ou null

Saque aprovado e ainda não pago: por que está esperando. awaiting_manual_transfer (a Koku vai fazer a transferência), in_review (transferência em análise), outside_window, daily_limit_reached ou monthly_limit_reached. null nos demais estados.

next_attempt_atstring (data e hora) ou null

Quando o saque em espera será reavaliado, quando houver previsão.

execution_channelstring

Como o saque é pago: manual_transfer (transferência feita pela Koku) ou partner (envio automático).

transfer_referencestring ou null

Saque pago por transferência da Koku: identificador da transferência (por exemplo, o fim a fim do Pix). A mesma referência aparece no extrato em payout.paid.

created_atstring (data e hora)

Momento do pedido.

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"`).
404	`not_found`	Saque inexistente ou de outra conta.
409	`conflict`	O saque já foi aprovado e está com a Koku para transferência (`details.reason = "payout_in_manual_transfer"`), ou já foi encaminhado.
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.

#Autenticação

#Parâmetros de caminho

#Corpo da requisição

#Resposta 200

#Erros

Autenticação

Parâmetros de caminho

Corpo da requisição

Resposta 200

Erros