> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Pix keys

> Register Pix keys on a wallet so it can receive Pix, confirm them, remove them, and answer claims from other institutions

A **Pix key** is an alias for a wallet's bank details. Payers send Pix to the key — a random key, a CNPJ or CPF, an e-mail address or a phone number — and the money reaches the wallet. Keys live in the Pix directory, where each key points to exactly one account. A wallet needs an active key to receive Pix by key and to issue Pix charges.

This guide covers registering a key, confirming one that needs a code, listing and removing keys, and answering the claims other institutions open for your keys.

## Key types

| `type` | `value` | Notes |
| - | - | - |
| `EVP` | Don't send one | A random key the bank generates for you, returned in `value`. The usual choice for a wallet per end customer. |
| `CNPJ` | 14 characters, no punctuation | Must be the account holder's own CNPJ. |
| `CPF` | 11 digits | Must be the account holder's own CPF. |
| `EMAIL` | A lowercase e-mail address | |
| `PHONE` | `+`, country code, area code and number (`+5511987654321`) | |

A key value can have at most 77 characters. A wallet can hold more than one key, up to the limit of the account.

## Register a key

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-dict' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "EVP" }'
```

The response (`201`) is the key. Keep its `_id` to manage it later, and give payers its `value`:

```json theme={null}
{
  "_id": "6728b1e2b4d3e80012c9a5a1",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "accountId": "66f2a1c7b4d3e80012c9a0b4",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "environment": "LIVE",
  "account": { "bankIspb": "12345678", "branch": "001", "number": 10023456, "type": "TRAN" },
  "external": { "entryId": "b6f1d2c3-4e5a-4b7c-9d8e-1f2a3b4c5d6e" },
  "status": "ACTIVE",
  "type": "EVP",
  "value": "9f1c2e7a-4b3d-4e8f-a6c1-2d5b7e9f0a13",
  "createdAt": "2026-11-04T14:05:12.348Z",
  "updatedAt": "2026-11-04T14:05:12.348Z",
  "__v": 0
}
```

Use `default` as `walletId` for the organization's main wallet.

The key usually comes back `ACTIVE`, ready to receive. If it comes back `PENDING_CONFIRMATION`, the phone number or e-mail address must be proven yours first — see [Confirm a key with a code](#confirm-a-key-with-a-code).

> [!NOTE]
>
> When registering fails, you get the error and the attempt stays in the wallet's list as a `FAILED` key, with the reason in `failReason`. If the bank refused the key (`422`) — for example, because another person or institution already holds it — nothing was registered: fix the cause and register the key again. If the bank failed or didn't answer in time (`5xx`), the key may have been registered anyway: registering the same key again then usually answers `ENTRY_ALREADY_EXISTS`, and support can reconcile it — except an `EVP`, which a retry registers again as a new random key.

Common refusals (`422`):

| `code` | What happened |
| - | - |
| `ENTRY_KEY_OWNED_BY_DIFFERENT_PERSON` | Another person or company holds the key. |
| `ENTRY_KEY_OWNED_BY_DIFFERENT_PARTICIPANT` | The key is registered at another bank or payment institution. Remove it there first. |
| `ENTRY_ALREADY_EXISTS` | The key is already registered for this account. |
| `EXCEEDED_ENTRIES_LIMIT` | The account already holds as many keys as it can. |
| `entry_locked_by_claim` | The key has an open claim. Wait until it is settled. |

Reference: [Register a Pix key](https://developers.portao3.com.br/api-reference/banking/pix-keys/register-a-pix-key.md)

## Confirm a key with a code

A `PENDING_CONFIRMATION` key waits for a code sent to its phone number or e-mail address.

1. [Request a code](https://developers.portao3.com.br/api-reference/banking/pix-keys/request-a-pix-key-confirmation-code.md) — `POST .../pix-dict/{pixDictId}/request-otp`, no body. It answers `204`.
2. [Confirm the key](https://developers.portao3.com.br/api-reference/banking/pix-keys/confirm-a-pix-key.md) with the code:

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-dict/{pixDictId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "otp": "482913" }'
```

The key comes back `ACTIVE` (`201`). A wrong or expired code is `422 INVALID_OTP_CODE` — request a new one. After too many attempts, `422 MAXIMUM_NUMBER_OF_ATTEMPTS_REACHED` asks you to wait 24 hours. Both routes answer `409 PIX_DICT_NOT_PENDING_CONFIRMATION` for a key that isn't waiting for a code.

## List keys

[List a wallet's keys](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-a-wallets-pix-keys.md) with `GET .../wallets/{walletId}/pix-dict`. Removed keys and failed attempts stay in the list, so filter by status to get the keys payers can use:

```bash theme={null}
curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-dict?status=ACTIVE' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

`status` takes several values, comma-separated (`?status=ACTIVE,PENDING_CONFIRMATION`). The response is an array, not paginated. Organization admins can also list every key of an [account](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-an-accounts-pix-keys.md) or of the [organization](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-an-organizations-pix-keys.md) at once.

## Remove a key

[Remove a key](https://developers.portao3.com.br/api-reference/banking/pix-keys/remove-a-pix-key.md) with `POST .../pix-dict/{pixDictId}/remove` and no body. It answers `204`. Pix sent to the key stop reaching the wallet, the key stays listed as `REMOVED`, and it can be registered again — here or elsewhere. Removing a key that is already `REMOVED`, or a `FAILED` attempt, succeeds and changes nothing — not even at the bank.

A key with an open claim can't be removed (`422 entry_locked_by_claim`): answer the claim first.

## Answer claims for your keys

Another institution can claim one of your keys on behalf of its customer:

* **Portability** (`type: "portability"`) — the key's owner asks to move the key to their account at the other institution.
* **Ownership** (`type: "ownership"`) — someone says a key you hold, an e-mail address or a phone number, is theirs.

[List the claims](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-an-organizations-pix-key-claims.md) with `GET /realms/{realmId}/organizations/{organizationId}/pix-dict-claim` (filter by `key`). Each claim says who is claiming (`claimer`), the account they want the key to point to (`claimerAccount`) and the deadline to answer (`resolutionPeriodEnd`). Answer a `waiting` claim before that deadline, using its `id` (not its `_id`):

* [Confirm it](https://developers.portao3.com.br/api-reference/banking/pix-keys/confirm-a-pix-key-claim.md) — `POST .../pix-dict-claim/{id}/confirm` — to **release** the key. This can't be undone. The key becomes `REMOVED` in your wallet when the Pix directory notifies the confirmation, which can come after the response.
* [Cancel it](https://developers.portao3.com.br/api-reference/banking/pix-keys/cancel-a-pix-key-claim.md) — `POST .../pix-dict-claim/{id}/cancel` — to **keep** the key.

Both answer `200` with the claim and the status the Pix directory answered (for example `confirmed`, `processing_confirm` or `canceled`). A claim that isn't `waiting` any more answers `404 PIX_DICT_CLAIM_NOT_FOUND`. Settled claims stay in the list with their final status (`completed`, `canceled`).

## Who can do what

| Action | Who |
| - | - |
| List a wallet's keys | Organization admins, and users the wallet is shared with (any role) |
| Register, confirm or remove a key | Organization admins, and users the wallet is shared with as `OWNER` or `USER` |
| List an account's or the organization's keys; list, confirm or cancel claims | Organization admins |

API clients act as admins of their organizations. Anyone else gets `403 FORBIDDEN_WALLET`.

If the bank throttles a request that reaches it — registering, confirming or removing a key, or answering a claim — you get a `429`: wait and retry.

## Next steps

> [card] [Charge with PIX](https://developers.portao3.com.br/guides/collect-pix.md)
>
> Generate a PIX QR Code (Copia e Cola) and get notified when it's paid.

> [card] [Wallets for your customers](https://developers.portao3.com.br/guides/wallets.md)
>
> Open a wallet per end customer, read balances, and move money between wallets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.