The Pix plugin manages all aspects of Pix key handling through a built-in DICT layer, including key registration, confirmation, deletion, listing, and portability requests. This functionality is fully aligned with BACEN regulations and integrated seamlessly into the plugin's orchestration flow.

Key registration

Users can register a Pix key of the following types:

Email
Phone number
CPF
CNPJ
EVP (random key)

Depending on the key type, the registration may be confirmed immediately (e.g. CPF, CNPJ, EVP), or require additional validation through a one-time code (e.g. email or phone).

If confirmation is required, the plugin will automatically handle the delivery of the code and track the confirmation status until it's either verified or expired.

Ownership confirmation

For email and phone keys, the user must confirm ownership using a time-sensitive one-time code. This step ensures that the person registering the key actually controls the email or phone being linked.

If the code expires or is invalid, the registration flow must be restarted.

👍
Tip
Ownership confirmation is time-limited. Make sure your interface clearly informs the user when a confirmation is required and when it times out.

Key listing

The plugin allows your system to retrieve all Pix keys associated with a given account. This is useful for displaying linked identifiers to users or managing key status.

Only confirmed keys are considered active and available for use in Pix transactions.

Key deletion

Pix keys can be removed from the DICT layer at any time. When deleted, the key is dissociated from the user’s account and becomes available for registration elsewhere, subject to BACEN’s standard release rules.

Deletion is idempotent: trying to delete an already-deleted or nonexistent key won’t cause errors.

Key portability and reclamation

If a user tries to register a Pix key that’s already associated with another institution, the Pix plugin supports initiating a portability or reclaim request.

This follows the official BACEN flow:

The request is submitted to the Pix network.
If eligible, the key is marked as claim_requested.
The external institution is notified and, if they approve, the key is transferred to your system.
If the key is not eligible (e.g. under dispute or blocked), the request is declined.

This process is fully handled by the plugin and complies with all required rules for Pix portability.

📘
Note
Reclamation is an asynchronous process. The final transfer depends on the response from the institution currently holding the key.

Cancelling a reclaim request

If a user changes their mind during the portability process, the reclaim request can be canceled before it is finalized. Once canceled, the key will remain registered to the original institution.

Error handling

The Pix plugin standardizes common error types and ensures graceful degradation. Some common scenarios include:

Invalid key format: The key doesn’t follow the expected format for its type.
Key already registered: A reclaim flow may be triggered automatically.
Expired confirmation: Ownership validation was not completed in time.
Key not found: Attempting to interact with a key that doesn't exist.

All validation rules are built-in and aligned with DICT and Pix standards.