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

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

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

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/put_pix_key_default" title="Set default key" method="PUT" path="/transactions/pix-keys/{pixKeyId}/default" />

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

The default key is the one that receives charges and the one that identifies your account in the transfers you send. To receive a transfer, any `ACTIVE` key works. Listing requires the `PIX_KEY_READ` scope; creating, deleting and changing the default require `PIX_KEY_WRITE`.

## Create [#create]

[`POST /transactions/pix-keys`](/docs/conta-digital/endpoints/pix-keys/post_pix_key). The account creates `EVP` (random) and `CNPJ` keys.

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

```json
{ "type": "CNPJ", "key": "12345678000195" }
```

For `EVP`, the key is generated by the bank: do not send `key`. For `CNPJ`, `key` is required and must be the account holder's CNPJ.

The response (`201`) carries the key already `ACTIVE`. The account's first key is created as the default.

```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"
}
```

Store the `id`: it is what goes in the routes to delete a key and to set the default, not the key value.

On a `502` with `PROVIDER_UNAVAILABLE`, the key may have been created. Repeat the same request: it reuses that key instead of creating another one.

## List [#list]

[`GET /transactions/pix-keys`](/docs/conta-digital/endpoints/pix-keys/get_pix_keys) returns the account's keys, the default first and the others from oldest to newest. The `status` of each one is `ACTIVE`, `PENDING` or `REMOVED`.

## Default key [#default-key]

[`PUT /transactions/pix-keys/{pixKeyId}/default`](/docs/conta-digital/endpoints/pix-keys/put_pix_key_default), with no body. The response (`200`) carries the key, now with `isDefault: true`. Only an `ACTIVE` key can be the default.

## Delete [#delete]

[`DELETE /transactions/pix-keys/{pixKeyId}`](/docs/conta-digital/endpoints/pix-keys/delete_pix_key). The response is `204`, with no body.

* The key leaves the DICT, the Pix key directory, and anyone who pays to it gets an error. Creating it again generates another key.
* The default key cannot be deleted. Set another one as the default first.
* Deleting a key that was already deleted responds `404`.

## Rejections [#rejections]

| Status | `code`                                   | When                                                                                                                                                                             |
| ------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `PIX_KEY_REQUIRED`                       | A type other than `EVP` without `key`.                                                                                                                                           |
| 400    | `PIX_KEY_RANDOM_KEY_NOT_ALLOWED`         | `EVP` with `key`.                                                                                                                                                                |
| 400    | `PIX_KEY_DOCUMENT_NOT_HOLDER`            | A CPF or CNPJ key that is not the holder's document.                                                                                                                             |
| 404    | `PIX_KEY_NOT_FOUND`                      | The key does not exist, was already deleted or belongs to another account.                                                                                                       |
| 409    | `PIX_KEY_DUPLICATED`                     | The key is already registered on this account.                                                                                                                                   |
| 422    | `PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER` | A type the account does not create: `CPF`, `EMAIL` or `PHONE`.                                                                                                                   |
| 422    | `PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT`     | The key is not `ACTIVE`.                                                                                                                                                         |
| 422    | `PIX_KEY_DEFAULT_CANNOT_BE_REMOVED`      | It is the default key.                                                                                                                                                           |
| 422    | `PIX_KEY_DEFAULT_ON_PROVIDER`            | The key is the account's default, even if the list did not show that yet. After the rejection, the list shows it as the default. Set another one as the default before deleting. |
| 422    | `PIX_KEY_PROVIDER_REFUSED`               | The bank refused the key. The reason comes in `details.reason`.                                                                                                                  |

Account and bank rejections, shared with other routes, are in [Error codes](/docs/conta-digital/error-codes). The full list for each route is in [Create Pix key](/docs/conta-digital/endpoints/pix-keys/post_pix_key), [Set default key](/docs/conta-digital/endpoints/pix-keys/put_pix_key_default) and [Delete Pix key](/docs/conta-digital/endpoints/pix-keys/delete_pix_key).