Create an Alias to a Virtual Account

Availability: Brazil

This setup allows merchants to associate unique identifiers, known as aliases, with virtual accounts, which are used to process local bank transfers through Pix.

In Brazil, configuring an alias for virtual bank accounts is a key step in enabling seamless and compliant payment experiences. By leveraging aliases, you can streamline the reconciliation process, enhance traceability, and ensure that incoming payments are correctly mapped to the intended transactions.

Info

• Once an alias has been configured, it cannot be modified. If changes are required, the existing alias must be canceled using the "Cancel Alias" service, and a new one must be created through the "Create Alias" process.
• For aliases of type email and phone number, this limitation is mitigated by a mandatory confirmation step (via email or SMS), which ensures the alias is valid and prevents erroneous configurations. If an alias of this type is confirmed, it means the information provided was correctly received and acknowledged by the user.
• To check which aliases are currently active on a virtual account, use the "Check Virtual Account" endpoint. This provides real-time status and visibility into the alias lifecycle.

Best Practices for Alias Management

• Use meaningful, consistent aliases to aid in internal reconciliation and support flows.
• Prefer email or phone number aliases where possible, as they provide a secure confirmation layer and reduce risk of misconfiguration.
• Build idempotency into your integration, especially when calling creation or cancellation endpoints, to avoid accidental duplicates or missed state transitions.
• Log alias creation responses and associate them with your internal transaction records for easy auditing.
• Use the status check endpoint periodically or before payment collection to verify the alias is still active and mapped correctly.