Saques
Listar contas de destino
https://api.kokupay.com/v1/beneficiaries Lista as contas bancárias da sua empresa cadastradas para receber saques, com os dados mascarados. Só uma conta com status = "verified" (titularidade conferida pela Koku) pode receber saque; use o id dela em beneficiary_account_id ao pedir o saque. O cadastro de contas é feito pelo painel, em Configurações → Dados bancários.
curl -X GET 'https://api.kokupay.com/v1/beneficiaries' \
-H "Authorization: Bearer $KOKU_API_KEY"const response = await fetch('https://api.kokupay.com/v1/beneficiaries', {
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/beneficiaries",
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/beneficiaries');
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);{
"items": [
{
"id": "e7a2c5f1-3b8d-4e60-a9c4-1f5b7d3e9a28",
"label": "Conta principal",
"version": 1,
"holder_name": "Loja Exemplo Ltda",
"holder_document_masked": "**********0001",
"pix_key_masked": "**********0001",
"bank_ispb": null,
"status": "verified",
"created_at": "2026-10-07T10:00:00.000Z"
}
]
}Autenticação
Authorization: Bearer <sua chave de API>
Escopo exigido: beneficiaries:read. Veja Chaves de API.
Resposta 200
itemslista de objetosItens da página.
items[].idstring (uuid)Identificador da conta de destino. Use em beneficiary_account_id ao pedir o saque.
items[].labelstringNome dado à conta no painel.
items[].versioninteiroVersão do cadastro (alterar os dados cria uma nova versão).
items[].holder_namestringNome do titular. Sempre a sua própria empresa.
items[].holder_document_maskedstringCNPJ do titular, mascarado (só os últimos dígitos).
items[].pix_key_maskedstring ou nullChave Pix da conta, mascarada; null quando a conta não tem chave Pix cadastrada.
items[].bank_ispbstring ou nullCódigo ISPB do banco; null quando a conta não tem dados bancários (agência e conta) cadastrados.
items[].statusstringSituação da conta: pending_verification (aguardando a Koku conferir a titularidade), verified (pode receber saques), rejected ou disabled.
items[].created_atstring (data e hora)Cadastro da conta.
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"). |
| 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.