Gerenciar chaves Pix

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

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

A resposta (201) é a chave. Guarde o _id para gerenciá-la depois e informe o value a quem vai pagar:

{
  "_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.

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

Confirmar uma chave com código

Uma chave PENDING_CONFIRMATION aguarda um código enviado para o seu telefone ou e-mail.

Solicite um código — POST .../pix-dict/{pixDictId}/request-otp, sem corpo. A resposta é 204.
Confirme a chave com o código:

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

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 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:

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 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 ou da organização.

Remover uma chave

Remova uma chave 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 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 — 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 — 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

Cobrar com PIX

Gere um PIX QR Code (Copia e Cola) e seja notificado quando ele for pago.

Carteiras para seus clientes

Abra uma carteira por cliente final, leia saldos e movimente dinheiro entre carteiras.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Gerenciar chaves Pix

Tipos de chave

Registrar uma chave

Confirmar uma chave com código

Listar chaves

Remover uma chave

Responder às reivindicações das suas chaves

Quem pode fazer o quê

Próximos passos

Cobrar com PIX

Carteiras para seus clientes

​Tipos de chave

​Registrar uma chave

​Confirmar uma chave com código

​Listar chaves

​Remover uma chave

​Responder às reivindicações das suas chaves

​Quem pode fazer o quê

​Próximos passos

Cobrar com PIX

Carteiras para seus clientes

Tipos de chave

Registrar uma chave

Confirmar uma chave com código

Listar chaves

Remover uma chave

Responder às reivindicações das suas chaves

Quem pode fazer o quê

Próximos passos