Manage Pix keys

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

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:

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

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

Confirm a key with a code

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

Request a code — POST .../pix-dict/{pixDictId}/request-otp, no body. It answers 204.
Confirm the key with the code:

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

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 or of the organization at once.

Remove a key

Remove a key 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 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 — 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 — 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.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Key types

Register a key

Confirm a key with a code

List keys

Remove a key

Answer claims for your keys

Who can do what

Next steps

Charge with PIX

Wallets for your customers

​Key types

​Register a key

​Confirm a key with a code

​List keys

​Remove a key

​Answer claims for your keys

​Who can do what

​Next steps

Charge with PIX

Wallets for your customers

Key types

Register a key

Confirm a key with a code

List keys

Remove a key

Answer claims for your keys

Who can do what

Next steps