Cadastrar chave PIX da subconta
POST
/api/subaccounts/{{subaccount_id}}/pix-keys
Autenticação
subaccounts:write e a conta precisa da flag white-label habilitada. Sem a flag, a rota responde 404 (invisível).Cadastrar chave PIX da subconta (delegado)
subaccounts:writestatus = PENDING_APPROVAL) — a aprovação humana é o gate de segurança. O caminho delegado não exige TOTP (autenticado pela API Key do master, mesmo precedente dos saques).Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | sim | CPF, CNPJ, EMAIL, PHONE ou RANDOM. |
key | string | sim | Valor da chave. É normalizado no servidor: CPF/CNPJ/telefone viram apenas dígitos (telefone recebe prefixo +55), email vira minúsculas. |
name | string | não | Nome do titular exibido. Default: o nome da subconta. |
Regras de negócio
type é CPF ou CNPJ, o valor normalizado da chave deve ser igual ao taxId da subconta. Caso contrário → 422 PIX_KEY_OWNERSHIP_MISMATCH.409.400.Resposta
201 Created com { pixKey: { id, type, key, status, createdAt }, message }. status será sempre PENDING_APPROVAL neste fluxo delegado.Códigos de erro
| HTTP | code | Quando |
|---|---|---|
400 | — | type/key ausentes, tipo inválido, ou chave com formato inválido. |
401 | — | Sem header Authorization ou chave inválida/revogada. |
403 | insufficient_scope | Chave sem o escopo subaccounts:write. |
404 | — | Flag white-label desabilitada, subconta inexistente ou não pertence ao master. |
409 | — | Chave PIX já cadastrada para a subconta. |
422 | PIX_KEY_OWNERSHIP_MISMATCH | CPF/CNPJ da chave diverge do taxId da subconta. |
Exemplo cURL
Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff '/api/subaccounts/{{subaccount_id}}/pix-keys' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"type": "CNPJ",
"key": "12345678000199",
"name": "Empresa Exemplo LTDA"
}'Response Response Example
201 - Sucesso (201) — enviada para aprovação
{
"pixKey": {
"id": "clpixkey0001",
"type": "CNPJ",
"key": "12345678000199",
"status": "PENDING_APPROVAL",
"createdAt": "2026-06-13T14:25:00.000Z"
},
"message": "Chave PIX enviada para aprovação do administrador."
}Modificado em 2026-07-02 06:57:27