# Chaves Pix (/docs/conta-digital/pix-keys)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/get_pix_keys" title="Listar chaves Pix" method="GET" path="/transactions/pix-keys" />

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/post_pix_key" title="Criar chave Pix" method="POST" path="/transactions/pix-keys" />

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/put_pix_key_default" title="Definir chave padrão" method="PUT" path="/transactions/pix-keys/{pixKeyId}/default" />

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/delete_pix_key" title="Apagar chave Pix" method="DELETE" path="/transactions/pix-keys/{pixKeyId}" />
</QuickLinks>

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 [#criar]

[`POST /transactions/pix-keys`](/docs/conta-digital/endpoints/pix-keys/post_pix_key). A conta cria chave `EVP` (aleatória) e `CNPJ`.

```json
{ "type": "EVP" }
```

```json
{ "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.

```json
{
  "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 [#listar]

[`GET /transactions/pix-keys`](/docs/conta-digital/endpoints/pix-keys/get_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 [#chave-padrão]

[`PUT /transactions/pix-keys/{pixKeyId}/default`](/docs/conta-digital/endpoints/pix-keys/put_pix_key_default), sem corpo. A resposta (`200`) traz a chave, agora com `isDefault: true`. Só chave `ACTIVE` pode ser padrão.

## Apagar [#apagar]

[`DELETE /transactions/pix-keys/{pixKeyId}`](/docs/conta-digital/endpoints/pix-keys/delete_pix_key). 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 [#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](/docs/conta-digital/error-codes). A lista completa de cada rota está em [Criar chave Pix](/docs/conta-digital/endpoints/pix-keys/post_pix_key), [Definir chave padrão](/docs/conta-digital/endpoints/pix-keys/put_pix_key_default) e [Apagar chave Pix](/docs/conta-digital/endpoints/pix-keys/delete_pix_key).