List, create and delete the account's Pix keys and choose which one is the default.
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
POST /transactions/pix-keys. The account creates EVP (random) and CNPJ keys.
{ "type": "EVP" }{ "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.
{
"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
GET /transactions/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
PUT /transactions/pix-keys/{pixKeyId}/default, with no body. The response (200) carries the key, now with isDefault: true. Only an ACTIVE key can be the default.
Delete
DELETE /transactions/pix-keys/{pixKeyId}. 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
| 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. The full list for each route is in Create Pix key, Set default key and Delete Pix key.