Documentation V3
  • Localpayment documentation V3
  • INTRODUCTION TO OUR SOLUTION
    • Intro to our Documentation
    • Intro to Payment Methods in Emerging Markets
    • Merchant Dashboard
      • Dashboard Navigation
      • Login
      • User Roles
      • Roles
      • Users
      • Whitelist your IPs
      • Whitelist your BINs
      • Setup your Webhooks
      • Reports
        • Balance
        • Projected Balance
        • Activity
        • Transaction Detail
        • FIDES Report
      • Virtual accounts
      • Refunds
        • Refund Bank Transfer
        • Refund Card Capture
        • Refund Cash
      • Chargeback
      • Internal Domestic Transfer
      • Internal Foreign Transfer
      • Currency Exchange
        • Create
      • Wire In
      • Wire Out
    • Intro to FX operations
    • Business definitions
      • Payins
      • Payouts
    • Onboarding & Integration
    • Postman Collection
  • ENVIRONMENTS
    • Environments
  • BEFORE A PAYMENT
    • Access Token
    • Validations
      • Document Validation
      • Bank Account Validation
      • Validate BIN
    • Holidays
    • Search Payment Method
    • Search Bank Codes
    • Cash Agents Geolocalization
    • Installments Plan Quote
    • Currency Exchange Quote
    • Billing Service
      • Create
        • Mexico
      • Check Billing status
      • Download Billing
  • REQUEST A PAYMENT
    • Payins
      • Bank Transfer
        • Direct debit
          • DEBIN (Argentina)
          • Transfiya (Colombia)
          • Wallet Fri (Guatemala)
        • Virtual Account
          • Mexico
            • Request Individual
            • Request Batch
            • Check Virtual account
            • Delete Virtual account
            • Enable or Disable Virtual Account
          • Brazil
            • Request Individual
            • Check Virtual account
            • Alias ​​configuration
          • Argentina
            • Request Individual
            • Request Batch
            • Check virtual account
            • Delete Virtual account
          • Refund Virtual Account
        • Online Reference Code Payments
          • Mexico
        • Refund Bank Transfer
        • Cancel
        • APMs
          • CODI (Mexico)
          • ETPAY (Chile)
          • Fintoc (Chile)
          • Boleto (Brazil)
          • PIX (Brazil)
            • Refund Pix
          • PSE (Colombia)
          • QR (Bolivia)
          • QR (Guatemala)
          • QR (Argentina)
          • QR (Perú)
      • Cash
        • Cash
          • APMs
            • Boleto (Brazil)
        • Cancel
        • Refund Cash
      • Debit Card
        • Capture
        • Refund Capture
      • Credit Card
        • Capture
        • Create Authorization
        • Capture Authorization
        • Cancel Authorization
        • Refund Capture
        • Installments
        • Save Cards
          • Save Card
          • Get Card
          • Delete Card
        • 3D-Secure
        • Validate card
        • Chargebacks
          • Notification
          • Send documentation
          • Close Chargeback
    • Payin Subscriptions
      • Create a subscription
      • Update subscription
      • Cancel
    • Payin Subscriptions Plan
      • Create subscription plan
      • Update subscription plan
      • Get subscription plan
    • Payouts
      • Search available banks
      • Create
        • Argentina
        • Bolivia
        • Brazil
        • Chile
        • Colombia
          • Colombia ACH
          • Colombia Transfiya
        • Costa Rica
        • Dominic Republic
        • Guatemala
        • Honduras
        • Mexico
        • Panama
        • Peru
        • Kenya
      • Manual Upload
        • Create Batch Upload
        • Batch Pending Authorization
        • Cancel Batch Pending Authorization
        • Batch Activity
      • Proof of Payment (POP)
      • Cancel
      • Commit payout
      • Attach documents
      • Ripplenet getway
    • Payouts Double Signature
      • Authorize
    • Checkout
      • Webcheckout
        • Credit Card
        • Debit Card
        • Cash
        • Bank Transfer
      • Link Payment
      • Frequent Items
      • Iframe
      • Smart Checkout/ iframe
      • Virtual Pos
      • Plugins
        • Magento
        • Shopify
        • Google Pay
        • WooCommerce
  • AFTER A PAYMENT
    • Check Status
    • Check Payment
    • Check Payment list
    • Check Subscription
    • Account Balance
      • Balance Reconciliation
      • Current Balance Amount
    • Withholding Certificates
    • Proof of Payment
    • RFI - Documentation
  • SETTLEMENT & EXCHANGE
    • Wire In
    • Wire Out
    • Currency Exchange Bulk
      • Quote
      • Bulk
      • Currency exchange - Front end
    • Internal Transfers
      • Internal Domestic Transfer
      • Internal Foreign Transfer
  • NOTIFICATIONS
    • Callbacks - Webhooks
      • Configurations
      • Payins
        • Payin Bank Transfer
        • PSE Colombia
        • Payin Virtual Account
        • Payin Cash
        • Payin Credit Card
        • Payin Debit Card
      • Payouts
    • SFTP- Email Reports
  • API REFERENCE GUIDE
    • Validation Error Codes
    • Transaction Type & Status
      • Payin
      • Subscriptions
      • Payout
      • Chargeback
      • Credit
      • Currency Exchange
      • Debit
      • Expenses
      • Internal Transfer
      • Recall
      • Refund
      • Return
      • Recurring Fee
      • Wire in
      • Wire out
    • Payout Methods + SLA
      • Latam
    • Payin Methods + SLA
      • Argentina
      • Bolivia
      • Brazil
      • Chile
      • Colombia
      • Dominican Republic
      • Guatemala
      • Mexico
      • Panama
      • Peru
    • Currency Codes
      • Latam
    • Country Codes
      • Latam
    • Bank codes
      • Latam
        • Argentina
        • Bolivia
        • Brazil
        • Chile
        • Colombia
        • Costa Rica
        • Dominican Republic
        • Guatemala
        • Honduras
        • Mexico
        • Panamá
        • Peru
    • Bank account validations
      • Latam
        • Argentina
        • Bolivia
        • Brazil
        • Chile
        • Colombia
        • Costa Rica
        • Dominican Republic
        • Guatemala
        • Mexico
        • Panama
        • Peru
    • Document Validations
      • Argentina
      • Bolivia
      • Brazil
      • Chile
      • Colombia
      • Costa Rica
      • Dominican Republic
      • El Salvador
      • Guatemala
      • Honduras
      • Mexico
      • Panama
      • Peru
    • Concept Codes
  • FLOWS AND CHARACTERISTICS
    • Account Currencies
    • Involved Parties
    • Payin Status Flow
      • Payins
        • Payin Status Flow - Card
        • Payin Status Flow - Bank
        • Payin Status Flow -Cash
      • Refund - Card
      • Refund - Cash & Bank
      • Chargeback
    • Payout Status Flow
      • Payout - Bank
      • Return
      • Recall
    • Payin Subscription Flow
      • Payins Subscription Status Flow - Card
    • Virtual Account Status Flow
    • Settlement Status Flow
      • Wire In
      • Wire Out
    • Payin Methods Flow
      • Argentina
      • Bolivia
      • Brazil
      • Chile
      • Colombia
      • Dominican Republic
      • Guatemala
      • Honduras
      • Mexico
      • Panama
      • Peru
  • HOLIDAYS
    • 2021
    • 2022
    • 2023
    • 2024
    • 2025
  • COMPLIANCE
    • Values
    • Prohibited Countries
    • Prohibited Business
    • Compliance Program Docs
    • Licenses
    • Terms & Conditions
  • GLOSSARY
    • Payments Explained
    • FAQ
  • PLUGINS
    • Magento
    • Shopify
    • Google Pay
    • WooCommerce
    • Ripplenet
Powered by GitBook
On this page
  • Best Practices for Alias Management
  • Alias Creation
  • Example: Configuration request
  • Alias Confirmation
  • Example: Confirmation request
  • Resend Token
  • Alias Cancellation

Was this helpful?

  1. REQUEST A PAYMENT
  2. Payins
  3. Bank Transfer
  4. Virtual Account
  5. Brazil

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.

PreviousCheck Virtual accountNextArgentina

Last updated 22 days ago

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.

Once an alias has been configured, it cannot be modified. If changes are required, the existing alias must be canceled using the "" service, and a new one must be created through the "" 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 "" 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.

Alias Creation

POST {{api_environment_url}}/api/virtual-account/{{ExternalIdVirtualAccount}}/alias

Configuration Alias of a Virtual Account

Request Body

Name
Type
Description

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

{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED",
        "detail": "Alias could not be created"
    }
}

Example: Configuration request

{
"type": "E",
"value": "Jose.perez@localpayment.com"
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED",
        "detail": "Alias could not be created"
    }
}

Please note that the information entered in the alias field must be valid and accurate. Once the request is submitted, a verification code will be sent to the associated email address or mobile phone number, depending on the selected type. This code will expire after 5 minutes and must be provided through the "Alias Confirmation" service to complete the confirmation process.

Alias Confirmation

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

Name
Type
Description

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

{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com",
        "confirmationCode": "221595"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias confirmed"
    }
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

Example: Confirmation request

{
"type": "E",
"value": "Jose.perez@localpayment.com",
"confirmationCode": "444088"
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com",
        "confirmationCode": "221595"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias confirmed"
    }
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

Resend Token

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

Name
Type
Description

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

{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}
{
"type": "E",
"value": "Jose.perez@localpayment.com"
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

Alias Cancellation

POST {{api_environment_url}}/api/virtual-account/{{ExternalIdVirtualAccount}}/alias/cancel

This service allows you to deactivate an alias that you are no longer using.

You must have at least one alias associated with your account at all times.

Body

Name
Type
Description

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

{ 
"externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias cancellation confirmed"
    }
  
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}
{
"type": "E",
"value": "Jose.perez@localpayment.com"
}
{ 
"externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias cancellation confirmed"
    }
  
}
{
    "externalId": "94b6faee-0b85-4304-915b-e857981b4c07",
    "alias": {
        "type": "E",
        "value": "Jose.perez@localpayment.com"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

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.

Check Virtual Account
Check Virtual Account
Cancel Alias
Create Alias