Chaves Pix
Liste, crie e apague as chaves Pix da conta e escolha qual delas é a padrão.
A chave padrão é a que recebe cobrança e a que identifica a sua conta nas transferências que você envia. Para receber transferência, vale qualquer chave ACTIVE. Listar exige o escopo PIX_KEY_READ; criar, apagar e trocar a padrão exigem PIX_KEY_WRITE.
Criar
POST /transactions/pix-keys. A conta cria chave EVP (aleatória) e CNPJ.
{ "type": "EVP" }{ "type": "CNPJ", "key": "12345678000195" }Na EVP, a chave é gerada pelo banco: não mande key. Na CNPJ, key é obrigatório e precisa ser o CNPJ do titular da conta.
A resposta (201) traz a chave já ACTIVE. A primeira chave da conta já nasce padrão.
{
"id": "cmu5k2x0a000301s6ab12cd34",
"key": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03",
"type": "EVP",
"status": "ACTIVE",
"isDefault": true,
"createdAt": "2026-09-17T14:32:05.123Z",
"updatedAt": "2026-09-17T14:32:05.123Z"
}Guarde o id: é ele, e não o valor da chave, que vai nas rotas de apagar e de definir a padrão.
Num 502 com PROVIDER_UNAVAILABLE, a chave pode ter sido criada. Repita o mesmo pedido: ele aproveita essa chave em vez de criar outra.
Listar
GET /transactions/pix-keys devolve as chaves da conta, a padrão primeiro e as outras da mais antiga para a mais nova. O status de cada uma é ACTIVE, PENDING ou REMOVED.
Chave padrão
PUT /transactions/pix-keys/{pixKeyId}/default, sem corpo. A resposta (200) traz a chave, agora com isDefault: true. Só chave ACTIVE pode ser padrão.
Apagar
DELETE /transactions/pix-keys/{pixKeyId}. A resposta é 204, sem corpo.
- A chave sai do DICT, o diretório de chaves do Pix, e quem pagar nela passa a receber erro. Criar de novo gera outra chave.
- A chave padrão não pode ser apagada. Defina outra como padrão antes.
- Apagar de novo uma chave já apagada responde
404.
Recusas
| Status | code | Quando |
|---|---|---|
| 400 | PIX_KEY_REQUIRED | Tipo diferente de EVP sem key. |
| 400 | PIX_KEY_RANDOM_KEY_NOT_ALLOWED | EVP com key. |
| 400 | PIX_KEY_DOCUMENT_NOT_HOLDER | Chave de CPF ou CNPJ que não é o documento do titular. |
| 404 | PIX_KEY_NOT_FOUND | A chave não existe, já foi apagada ou é de outra conta. |
| 409 | PIX_KEY_DUPLICATED | A chave já está cadastrada nesta conta. |
| 422 | PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER | Tipo que a conta não cria: CPF, EMAIL ou PHONE. |
| 422 | PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT | A chave não está ACTIVE. |
| 422 | PIX_KEY_DEFAULT_CANNOT_BE_REMOVED | É a chave padrão. |
| 422 | PIX_KEY_DEFAULT_ON_PROVIDER | A chave é a padrão da conta, mesmo que a listagem ainda não mostrasse isso. Depois da recusa, a listagem passa a mostrá-la como padrão. Defina outra como padrão antes de apagar. |
| 422 | PIX_KEY_PROVIDER_REFUSED | O banco recusou a chave. O motivo vem em details.reason. |
As recusas de conta e de banco, comuns a outras rotas, estão em Códigos de erro. A lista completa de cada rota está em Criar chave Pix, Definir chave padrão e Apagar chave Pix.