Alias configuration
This setup allows merchants to associate unique identifiers, known as aliases, with virtual accounts, which are used to process local bank transfers through Pix.
Last updated
Was this helpful?
This setup allows merchants to associate unique identifiers, known as aliases, with virtual accounts, which are used to process local bank transfers through Pix.
Last updated
Was this helpful?
In Brazil, configuring an alias for virtual bank accounts is a key step in enabling seamless and compliant payment experiences. This setup allows merchants and partners to associate unique identifiers—known as aliases—with virtual accounts, which are used for processing local bank transfers via Pix. By leveraging aliases, you can streamline the reconciliation process, enhance traceability, and ensure that incoming payments are correctly mapped to the intended transactions.
To check which aliases are currently active on a virtual account, use the "" endpoint. This provides real-time status and visibility into the alias lifecycle.
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.
POST {{api_environment_url}}/api/virtual-account/{{ExternalIdVirtualAccount}}/alias
Configuration Alias of a Virtual Account
Request Body
type*
string
The type of alias to be associated can be 'E' for email or 'P' for phone number.
value*
string
Value indicating the type of alias to be configured—either an email address or a phone number.
Response
Once the previous action is completed and you have the code, you must execute this confirmation service.
POST {{api_environment_url}}/api/virtual-account/{{ExternalIdVirtualAccount}}/alias/confirm
Body
type*
string
The type of alias to be associated can be 'E' for email or 'P' for phone number.
value*
string
Value indicating the type of alias to be configured—either an email address or a phone number.
confirmationCode*
string
Confirmation code generated when executing the account configuration service
Response
POST {{api_environment_url}}/api/virtual-account/{{ExternalIdVirtualAccount}}/alias/resendcode
The "Token Resend" functionality is intended to support users who did not receive or were unable to use the original verification token within the designated timeframe. This feature allows the user to request a new token to be sent to their registered communication channel (email or mobile phone), ensuring uninterrupted progression of the alias confirmation or registration process.
Body Request
Type*
string
The type of alias to be associated can be 'E' for email or 'P' for phone number.
Value*
string
Value indicating the type of alias to be configured—either an email address or a phone number.
Response
POST {{api_environment_url}}/api/virtual-account/{{ExternalIdVirtualAccount}}/alias/cancel
This service allows you to deactivate an alias that you are no longer using.
Body
Type*
string
The type of alias to be associated can be 'E' for email or 'P' for phone number.
Value*
string
Value indicating the type of alias to be configured—either an email address or a phone number.
Response
To check which aliases are currently active on a virtual account, use the endpoint. This provides real-time status and visibility into the alias lifecycle.