> ## 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. # Gerenciar chaves Pix > Registre chaves Pix em uma carteira para que ela receba Pix, confirme-as, remova-as e responda às reivindicações de outras instituições Uma **chave Pix** é um apelido para os dados bancários de uma carteira. Quem paga envia o Pix para a chave — uma chave aleatória, um CNPJ ou CPF, um e-mail ou um telefone — e o dinheiro chega à carteira. As chaves ficam no diretório do Pix, onde cada chave aponta para uma única conta. Uma carteira precisa de uma chave ativa para receber Pix por chave e para emitir cobranças Pix. Este guia cobre como registrar uma chave, confirmar uma que precisa de código, listar e remover chaves e responder às reivindicações que outras instituições abrem para as suas chaves. ## Tipos de chave | `type` | `value` | Observações | | - | - | - | | `EVP` | Não envie | Uma chave aleatória que o banco gera para você, devolvida em `value`. A escolha usual para uma carteira por cliente final. | | `CNPJ` | 14 caracteres, sem pontuação | Precisa ser o CNPJ do próprio titular da conta. | | `CPF` | 11 dígitos | Precisa ser o CPF do próprio titular da conta. | | `EMAIL` | Um e-mail em minúsculas | | | `PHONE` | `+`, código do país, DDD e número (`+5511987654321`) | | O valor de uma chave tem no máximo 77 caracteres. Uma carteira pode ter mais de uma chave, até o limite da conta. ## Registrar uma chave ```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 ' \ -H 'x-environment: LIVE' \ -H 'Content-Type: application/json' \ -d '{ "type": "EVP" }' ``` A resposta (`201`) é a chave. Guarde o `_id` para gerenciá-la depois e informe o `value` a quem vai pagar: ```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` como `walletId` para a carteira principal da organização. A chave normalmente volta `ACTIVE`, pronta para receber. Se voltar `PENDING_CONFIRMATION`, é preciso provar primeiro que o telefone ou o e-mail é seu — veja **Confirmar uma chave com código**, abaixo. > [!NOTE] > > Quando o registro falha, você recebe o erro, e a tentativa fica na lista da carteira como uma chave `FAILED`, com o motivo em `failReason`. Se o banco recusou a chave (`422`) — por exemplo, porque outra pessoa ou instituição já a possui —, nada foi registrado: corrija a causa e registre a chave de novo. Se o banco falhou ou não respondeu a tempo (`5xx`), a chave pode ter sido registrada mesmo assim: registrar a mesma chave de novo então costuma responder `ENTRY_ALREADY_EXISTS`, e o suporte pode reconciliá-la — exceto uma `EVP`, que uma nova tentativa registra como outra chave aleatória. Recusas comuns (`422`): | `code` | O que aconteceu | | - | - | | `ENTRY_KEY_OWNED_BY_DIFFERENT_PERSON` | Outra pessoa ou empresa possui a chave. | | `ENTRY_KEY_OWNED_BY_DIFFERENT_PARTICIPANT` | A chave está registrada em outro banco ou instituição de pagamento. Remova-a lá primeiro. | | `ENTRY_ALREADY_EXISTS` | A chave já está registrada para esta conta. | | `EXCEEDED_ENTRIES_LIMIT` | A conta já tem o máximo de chaves que pode ter. | | `entry_locked_by_claim` | A chave tem uma reivindicação em aberto. Aguarde até que ela seja resolvida. | Referência: [Register a Pix key](https://developers.portao3.com.br/api-reference/banking/pix-keys/register-a-pix-key.md) ## Confirmar uma chave com código Uma chave `PENDING_CONFIRMATION` aguarda um código enviado para o seu telefone ou e-mail. 1. [Solicite um código](https://developers.portao3.com.br/api-reference/banking/pix-keys/request-a-pix-key-confirmation-code.md) — `POST .../pix-dict/{pixDictId}/request-otp`, sem corpo. A resposta é `204`. 2. [Confirme a chave](https://developers.portao3.com.br/api-reference/banking/pix-keys/confirm-a-pix-key.md) com o código: ```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 ' \ -H 'x-environment: LIVE' \ -H 'Content-Type: application/json' \ -d '{ "otp": "482913" }' ``` A chave volta `ACTIVE` (`201`). Um código errado ou expirado é `422 INVALID_OTP_CODE` — solicite outro. Depois de tentativas demais, `422 MAXIMUM_NUMBER_OF_ATTEMPTS_REACHED` pede que você espere 24 horas. As duas rotas respondem `409 PIX_DICT_NOT_PENDING_CONFIRMATION` para uma chave que não está aguardando código. ## Listar chaves [Liste as chaves de uma carteira](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-a-wallets-pix-keys.md) com `GET .../wallets/{walletId}/pix-dict`. Chaves removidas e tentativas que falharam continuam na lista, então filtre pelo status para obter as chaves que podem receber: ```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 ' \ -H 'x-environment: LIVE' ``` `status` aceita vários valores, separados por vírgula (`?status=ACTIVE,PENDING_CONFIRMATION`). A resposta é um array, sem paginação. Administradores da organização também podem listar de uma vez todas as chaves de uma [conta](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-an-accounts-pix-keys.md) ou da [organização](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-an-organizations-pix-keys.md). ## Remover uma chave [Remova uma chave](https://developers.portao3.com.br/api-reference/banking/pix-keys/remove-a-pix-key.md) com `POST .../pix-dict/{pixDictId}/remove`, sem corpo. A resposta é `204`. Os Pix enviados para a chave deixam de chegar à carteira, a chave continua listada como `REMOVED` e pode ser registrada de novo — aqui ou em outra instituição. Remover uma chave que já está `REMOVED`, ou uma tentativa `FAILED`, funciona e não altera nada — nem no banco. Uma chave com reivindicação em aberto não pode ser removida (`422 entry_locked_by_claim`): responda à reivindicação primeiro. ## Responder às reivindicações das suas chaves Outra instituição pode reivindicar uma das suas chaves em nome de um cliente dela: * **Portabilidade** (`type: "portability"`) — o dono da chave pede para levá-la para a conta dele na outra instituição. * **Reivindicação de posse** (`type: "ownership"`) — alguém afirma que uma chave que você possui, um e-mail ou um telefone, é dele. [Liste as reivindicações](https://developers.portao3.com.br/api-reference/banking/pix-keys/list-an-organizations-pix-key-claims.md) com `GET /realms/{realmId}/organizations/{organizationId}/pix-dict-claim` (filtre por `key`). Cada reivindicação informa quem reivindica (`claimer`), a conta para a qual a chave passaria a apontar (`claimerAccount`) e o prazo para responder (`resolutionPeriodEnd`). Responda a uma reivindicação `waiting` antes desse prazo, usando o `id` dela (não o `_id`): * [Confirme-a](https://developers.portao3.com.br/api-reference/banking/pix-keys/confirm-a-pix-key-claim.md) — `POST .../pix-dict-claim/{id}/confirm` — para **liberar** a chave. Isso não pode ser desfeito. A chave fica `REMOVED` na sua carteira quando o diretório do Pix notifica a confirmação, o que pode acontecer depois da resposta. * [Cancele-a](https://developers.portao3.com.br/api-reference/banking/pix-keys/cancel-a-pix-key-claim.md) — `POST .../pix-dict-claim/{id}/cancel` — para **manter** a chave. As duas respondem `200` com a reivindicação e o status que o diretório do Pix devolveu (por exemplo `confirmed`, `processing_confirm` ou `canceled`). Uma reivindicação que não está mais `waiting` responde `404 PIX_DICT_CLAIM_NOT_FOUND`. Reivindicações encerradas continuam na lista com o status final (`completed`, `canceled`). ## Quem pode fazer o quê | Ação | Quem | | - | - | | Listar as chaves de uma carteira | Administradores da organização e usuários com quem a carteira foi compartilhada (qualquer papel) | | Registrar, confirmar ou remover uma chave | Administradores da organização e usuários com quem a carteira foi compartilhada como `OWNER` ou `USER` | | Listar as chaves de uma conta ou da organização; listar, confirmar ou cancelar reivindicações | Administradores da organização | API clients atuam como administradores das suas organizações. Qualquer outra pessoa recebe `403 FORBIDDEN_WALLET`. Se o banco limitar uma requisição que chega até ele — registrar, confirmar ou remover uma chave, ou responder a uma reivindicação —, você recebe um `429`: aguarde e tente de novo. ## Próximos passos > [card] [Cobrar com PIX](https://developers.portao3.com.br/pt-BR/guides/collect-pix.md) > > Gere um PIX QR Code (Copia e Cola) e seja notificado quando ele for pago. > [card] [Carteiras para seus clientes](https://developers.portao3.com.br/pt-BR/guides/wallets.md) > > Abra uma carteira por cliente final, leia saldos e movimente dinheiro entre carteiras. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.