Manage Virtual Account Aliases

Aliases simplify the payment process by replacing a 22-digit CVU with a short, human-readable text string that is easier to share and remember.

Availability

Virtual Account alias management is available in the following countries:

Before You Begin

Ensure you have:

• Valid API credentials (access token).
• The externalId of an active virtual account in COMPLETED status.

How Aliases Work in Argentina

Argentina supports CVU aliases for virtual accounts. Key characteristics:

• Format: Letters (a–z, A–Z), numbers (0–9), and dots (.) only. No spaces, hyphens, underscores, or special characters.
• Length: Between 5 and 20 characters.
• Uniqueness: The alias must be unique at the country level. This is not a platform restriction, but a requirement of the Argentine banking system. If another CVU already uses the same alias, the request will be rejected.
• Updating an alias: To update an alias, call the same endpoint with the new value once the required waiting period has elapsed.
• Change limit: Once set or updated, an alias cannot be changed again for 24 hours. The alias can be updated a maximum of 10 times in total.
• Asynchronous activation: The alias is activated in the background. An INPROGRESS response does not mean the alias is already active. Verify activation using Get Virtual Account Status.

Valid alias examples: alias.example · alias.example2026 · alias.example.test

Invalid alias examples: alias example (space) · alias-example (hyphen) · alias_example (underscore) · alias@example (at sign)

Set Virtual Account Alias

Set a custom alias for an existing active virtual account. This operation both assigns a new alias and updates an existing one. The same endpoint handles both cases.

Key Request Parameters

Example Request

curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/alias \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "type": "C",
  "value": "alias.example"
}'

See all available parameters in the API reference.

Successful Response

{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}

Verify Alias Activation

After receiving an INPROGRESS response, query the virtual account to confirm the alias is active. Send a GET request to the individual status endpoint:

curl --request GET \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId} \
     --header 'Authorization: Bearer <your_access_token>'

Once the alias is active, it appears in beneficiary.bank.account.alias:

{
    "currency": "ARS",
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "accountNumber": "0000003100099999999015",
    "beneficiary": {
        "type": "COMPANY",
        "name": "Example Company S.A.",
        "fullName": "Example Company S.A.",
        "document": {
            "type": "CUIT",
            "id": "30-71234567-9"
        },
        "bank": {
            "account": {
                "number": "0000003100099999999015",
                "alias": [
                    {
                        "type": "C",
                        "value": "alias.example"
                    }
                ]
            }
        }
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "Virtual account has been created"
    },
    "errors": [],
    "disabled": false
}

If the alias configuration fails asynchronously after an INPROGRESS response, the error will appear in the errors array of this same response. Poll the status endpoint until errors is empty and the alias is visible in beneficiary.bank.account.alias.

Key Response Fields

Error Responses

The following error codes apply to the synchronous response. If the initial response is INPROGRESS, the operation has been accepted, but errors may still occur during asynchronous processing. To detect these, query Get Virtual Account Status and check the errors array.

{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "776",
        "description": "REJECTED",
        "detail": "The alias is already in use; please select a different alias."
    }
}

Common Error Scenarios

Demo

Next Steps