Listar saques · Documentação Koku

GEThttps://api.kokupay.com/v1/payouts

Lista os saques pedidos pela sua empresa (pelo painel ou pela API), dos mais recentes para os mais antigos, com paginação por cursor. Os repasses que a Koku fez sem pedido ficam em Listar repasses feitos pela Koku.

GET/v1/payouts

curl -X GET 'https://api.kokupay.com/v1/payouts' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/payouts', {
  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",
    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');
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);

200Resposta

{
  "items": [
    {
      "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"
    },
    {
      "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"
    }
  ],
  "next_cursor": null
}

Autenticação

Authorization: Bearer <sua chave de API>

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

Parâmetros de consulta

cursorstring

Cursor devolvido em next_cursor da página anterior.

até 2000 caracteres

limitinteiro

Itens por página.

de 1 a 200

Resposta 200

itemslista de objetos

Itens da página.

items[].idstring (uuid)

Identificador do saque.

items[].gateway_idstring (uuid)

Identificador da sua conta na Koku.

items[].environmentstring

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

Valores: sandbox, production

items[].requested_centsstring (centavos)

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

items[].fee_centsstring (centavos)

Taxa de saque descontada do valor pedido, em centavos.

items[].amount_centsstring (centavos)

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

items[].currencystring

Moeda (BRL).

Valores: BRL

items[].beneficiary_account_idstring (uuid)

Conta de destino do saque.

items[].destinationobjeto

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

items[].destination.holder_namestring

Nome do titular da conta de destino.

items[].destination.holder_document_maskedstring

CNPJ do titular, mascarado.

items[].destination.pix_key_maskedstring ou null

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

items[].destination.bank_ispbstring ou null

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

items[].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.

items[].approval_modestring ou null

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

items[].approval_reasonstring ou null

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

items[].approval_decided_atstring (data e hora) ou null

Momento da decisão. null enquanto pendente.

items[].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).

items[].scheduled_forstring (data e hora) ou null

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

items[].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.

items[].confirmed_atstring (data e hora) ou null

Momento em que o saque foi pago.

items[].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.

items[].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.

items[].awaiting_second_approvalbooleano

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

items[].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.

items[].next_attempt_atstring (data e hora) ou null

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

items[].execution_channelstring

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

items[].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.

items[].created_atstring (data e hora)

Momento do pedido.

next_cursorstring ou null

Cursor da próxima página; null quando não há mais itens.

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"`).
422	`validation_error`	Cursor adulterado ou `limit` fora de 1 a 200.
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 consulta

#Resposta 200

#Erros

Autenticação

Parâmetros de consulta

Resposta 200

Erros