Docs
Acessar painel

Saques

Listar contas de destino

GEThttps://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.

GET/v1/beneficiaries
curl -X GET 'https://api.kokupay.com/v1/beneficiaries' \
  -H "Authorization: Bearer $KOKU_API_KEY"
200Resposta
{
  "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 objetos

Itens da página.

items[].idstring (uuid)

Identificador da conta de destino. Use em beneficiary_account_id ao pedir o saque.

items[].labelstring

Nome dado à conta no painel.

items[].versioninteiro

Versão do cadastro (alterar os dados cria uma nova versão).

items[].holder_namestring

Nome do titular. Sempre a sua própria empresa.

items[].holder_document_maskedstring

CNPJ do titular, mascarado (só os últimos dígitos).

items[].pix_key_maskedstring ou null

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

items[].bank_ispbstring ou null

Código ISPB do banco; null quando a conta não tem dados bancários (agência e conta) cadastrados.

items[].statusstring

Situaçã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

StatusCódigoQuando
401unauthorizedChave ausente, inválida, revogada ou expirada.
403forbiddenA chave não tem o escopo exigido (details.reason = "missing_scope").
429rate_limitedLimite de requisições excedido. Aguarde o tempo de Retry-After.
500internal_errorFalha inesperada. Repita com a mesma Idempotency-Key; persistindo, envie o correlation_id à Koku (veja Suporte).

Formato do corpo de erro em Erros.