Manage Virtual Account Aliases

Localpayment allows you to create and manage aliases for virtual accounts, providing memorable references that can be used instead of account numbers for payments. Aliases simplify the payment process for customers while maintaining the security of unique virtual account numbers.

Availability

Virtual Account alias management is available in the following countries:

Country	Supported Operations	Supported Alias Types
Argentina	—
Brazil	Create, Confirm, Cancel	Email, Phone (must start with the +55 country prefix for Brazil), Random Key
Mexico	—
Peru	—

Before You Begin

Ensure you have:

Valid API credentials(access token).
Virtual account external ID you want to manage aliases for.

Virtual Account Alias Management

Manage virtual account aliases using the following API operations:

Create Virtual Account Alias

Generate a new alias for a virtual account.

Confirm Alias Creation

Confirm alias creation using the verification code sent to the beneficiary.

Cancel Alias

Remove an existing alias from a virtual account.

Country-Specific Requirements

Implementation details vary by country. Review these requirements before integration:

Alias Types Supported:

Email (E): Valid email address format
Phone (P): Brazilian phone number format with +55 country code
Random Key (R): Auto-generated by Localpayment during virtual account creation

Requirements:

All alias types require confirmation via the provided contact method
Phone aliases must use Brazilian format: +55 followed by area code and number
Email aliases must be valid and accessible email addresses
A PIX alias can only be linked to one virtual account at a time. Attempting to assign an alias already in use will result in an error.

Verification Process:

Verification code is valid for 5 minutes
Code is sent to the registered email or phone number provided during creation
Multiple confirmation attempts are allowed within the 5-minute window
New verification codes can be requested after expiration

Phone Number Format:

Brazilian phone numbers must follow this exact format:

Country code: +55
Area code: 2 digits (e.g., 11 for São Paulo, 21 for Rio de Janeiro)
Number: 8 or 9 digits
Example: +5511999999999

Create Virtual Account Alias

Generate a new alias for a virtual account. This requires confirmation before the alias becomes active.

For phone number aliases, ensure the number starts with the Brazilian country prefix +55.

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
externalId	The external ID of the virtual account (path parameter).	✅
type	Type of alias (`E` = Email, `P` = Phone).	✅
value	The alias value (email or phone).	✅

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "E",
  "value": "[email protected]"
}
'

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "P",
  "value": "+551199999999"
}
'

See all available parameters in the request.

Successful Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}

Key Response Fields

Field	Description	Use Case
`alias.type`	Type of alias created (E, P)	Type-specific handling
`alias.value`	The alias value that was created	Verification
`status.code`	Current alias status code	Determine next steps

Error Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "802",
        "description": "REJECTED",
        "detail": "Alias could not be created"
    }
}

Confirm Virtual Account Alias Creation

Confirm an alias creation using the 5-minute verification code sent to the beneficiary.

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
externalId	The external ID of the virtual account (path parameter).	✅
type	Type of alias (`E` = Email, `P` = Phone).	✅
value	The alias value (email or phone).	✅
confirmationCode	The 5-minute verification code received by the beneficiary.	✅

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/confirm \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "E",
  "value": "[email protected]",
  "confirmationCode": "123456"
}
'

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "P",
  "value": "+551199999999"
}
'

See all available parameters in the request.

Successful Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]",
        "confirmationCode": "221595"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias confirmed"
    }
}

Key Response Fields

Field	Description	Use Case
`alias.type`	Type of alias created (E, P)	Type-specific handling
`alias.value`	The alias value that was created	Verification
`alias.confirmationCode`	The confirmation code that was used	Audit trail
`status.code`	Current alias status code	Determine next steps

Error Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

Request a New Confirmation Code

Request a new 5-minute verification code if the previous code expired or was not received.

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
externalId	The external ID of the virtual account (path parameter).	✅
type	Type of alias (`E` = Email, `P` = Phone).	✅
value	The alias value (email or phone).	✅

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/resendcode \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "E",
  "value": "[email protected]"
}
'

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "P",
  "value": "+551199999999"
}
'

See all available parameters in the request.

Successful Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}

Key Response Fields

Field	Description	Use Case
`alias.type`	Type of alias created (E, P)	Type-specific handling
`alias.value`	The alias value that was created	Verification
`status.code`	Current alias status code	Determine next steps

Error Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

Cancel Virtual Account Alias

Remove an existing alias from a virtual account. Once cancelled, an alias cannot be reactivated or modified - it must be registered again with the full verification process. Canceling an alias deactivates it permanently, preventing any further payments from being processed through that alias.

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
externalId	The external ID of the virtual account (path parameter).	✅
type	Type of alias (`E` = Email, `P` = Phone).	✅
value	The alias to cancel	✅

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/cancel \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "E",
  "value": "[email protected]"
}
'

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "type": "P",
  "value": "+551199999999"
}
'

See all available parameters in the request.

Successful Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias cancellation confirmed"
    }
}

Key Response Fields

Field	Description	Use Case
`alias.type`	Type of alias created (E, P)	Type-specific handling
`alias.value`	The alias value that was canceled	Verification
`status.code`	Cancellation status code	Determine next steps

Error Response

{
    "externalId": "94c6faee-0b35-4304-915b-e857981b4c01",
    "alias": {
        "type": "E",
        "value": "[email protected]"
    },
    "status": {
        "code": "802",
        "description": "REJECTED"
    }
}

Next Steps

After managing virtual account aliases, you may want to:

Create Virtual Accounts

Generate new virtual accounts that can be enhanced with aliases.

Manage Virtual Account Status

Check the status of virtual accounts and their associated aliases.

API Integration Guide

Explore best practices for API integration and error handling.