Consultar um saque · Documentação Koku

GEThttps://api.kokupay.com/v1/payouts/{id}

Devolve o saque com a situação atual da análise (approval_status) e da transferência (execution_status). Quando pago, transfer_reference traz o identificador da transferência feita pela Koku.

GET/v1/payouts/{id}

curl -X GET 'https://api.kokupay.com/v1/payouts/a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/payouts/a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74', {
  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/payouts/a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
    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/payouts/a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74');
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);

Respostas

200 · Consultar um saque

{
  "id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "requested_cents": "5000",
  "fee_cents": "500",
  "amount_cents": "4500",
  "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": "reserved",
  "scheduled_for": null,
  "submitted_at": null,
  "confirmed_at": null,
  "end_to_end_id": null,
  "failure_reason": null,
  "awaiting_second_approval": false,
  "waiting_reason": null,
  "next_attempt_at": null,
  "execution_channel": "manual_transfer",
  "transfer_reference": null,
  "created_at": "2026-10-10T17:00:00.000Z"
}

200 · Saque pago pela Koku

{
  "id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "requested_cents": "5000",
  "fee_cents": "500",
  "amount_cents": "4500",
  "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": "approved",
  "approval_mode": "manual",
  "approval_reason": "Conferido",
  "approval_decided_at": "2026-10-12T12:10:00.000Z",
  "execution_status": "paid",
  "scheduled_for": null,
  "submitted_at": null,
  "confirmed_at": "2026-10-12T13:00:00.000Z",
  "end_to_end_id": null,
  "failure_reason": null,
  "awaiting_second_approval": false,
  "waiting_reason": null,
  "next_attempt_at": null,
  "execution_channel": "manual_transfer",
  "transfer_reference": "E98765432202610121300Sq4Ke7Mn2Pw",
  "created_at": "2026-10-10T17:00:00.000Z"
}

404 · Saque inexistente

{
  "error": {
    "code": "not_found",
    "message": "Repasse não encontrado.",
    "details": {},
    "correlation_id": "6b2d8f4a-1c7e-4e93-a5d0-9f3c7b1e4a62"
  }
}

Autenticação

Authorization: Bearer <sua chave de API>

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

Parâmetros de caminho

idstring (uuid)obrigatório

Identificador do saque.

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.
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

#Resposta 200

#Erros

Autenticação

Parâmetros de caminho

Resposta 200

Erros