Listar subcontas
GET
/api/subaccounts
Autenticação
subaccounts:read. Sem a flag whiteLabelEnabled → 404.Listar subcontas
subaccounts:readcreatedAt desc. Subcontas excluídas (soft delete) são omitidas desta listagem.Query params
| Param | Tipo | Default | Descrição |
|---|---|---|---|
page | int | 1 | Página (≥1). |
limit | int | 50 | Itens por página (1–100). |
search | string | — | Busca em name, email, correlationId e taxId (dígitos). |
kycStatus | string | — | Filtra por status de KYC. Valores inválidos são silenciosamente ignorados. Ex.: PRE_APPROVED, PENDING, APPROVED, REJECTED. |
Resposta
200 OK com { data: [...], pagination: { page, limit, total, pages } }. Cada item traz balance em CENTAVOS (available, reserved) e o resumo das chaves PIX (id, status).Sigilo: a listagem expõe apenas a posição da subconta. Nenhuma decomposição de taxa/comissão do master aparece aqui.
Erros
| HTTP | Quando |
|---|---|
| 401 | API key ausente/inválida. |
| 403 | Escopo subaccounts:read ausente. |
| 404 | Sem a flag whiteLabelEnabled. |
Exemplo cURL
Requisição
Parâmetros de Consulta
Parâmetros Header
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/subaccounts?page=1&limit=50' \
--header 'Authorization: Bearer <token>'Response Response Example
200 - Sucesso (200)
{
"data": [
{
"id": "{{subaccount_id}}",
"correlationId": "seller-001",
"name": "Loja do João LTDA",
"email": "financeiro@lojadojoao.com.br",
"taxId": "12345678000199",
"taxIdType": "CNPJ",
"kycStatus": "PRE_APPROVED",
"balance": {
"available": 125000,
"reserved": 0
},
"pixKeys": [
{
"id": "{{pix_key_id}}",
"status": "APPROVED"
}
],
"createdAt": "2026-06-12T14:30:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"pages": 1
}
}Modificado em 2026-07-02 06:57:27