> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Administrar alias de cuentas virtuales

Localpayment te permite crear y administrar alias para cuentas virtuales en Argentina, ofreciendo referencias fáciles de recordar que pueden utilizarse en lugar de los números de CVU para realizar pagos.

Los alias simplifican el proceso de pago al reemplazar un CVU de 22 dígitos por una cadena de texto corta y legible, más fácil de compartir y de recordar.

## Disponibilidad

La gestión de alias de cuentas virtuales está disponible en los siguientes países:

| País | Operaciones admitidas | Tipos de alias admitidos |
| - | - | :- |
| [Argentina](https://docs.localpayment.com/es/docs/argentina.md) | Establecer alias | Personalizable (`C`): texto definido por el usuario |
| [Brasil](https://docs.localpayment.com/es/docs/brazil.md) | N / A | |
| [Colombia](https://docs.localpayment.com/es/docs/colombia.md) | N / A | |
| [México](https://docs.localpayment.com/es/docs/mexico.md) | N / A | |
| [Perú](https://docs.localpayment.com/es/docs/peru.md) | N / A | |

***

## Antes de comenzar

Asegúrate de tener:

* [Credenciales API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).
* El `externalId` de una cuenta virtual activa en estado `COMPLETED`.

> [!WARNING]
>
> Una cuenta virtual debe estar en estado `COMPLETED` antes de que puedas asignarle un alias. Esta transición de estado es automática.

***

## Cómo funcionan los alias en Argentina

Argentina admite **alias de CVU** para cuentas virtuales. Características principales:

* **Formato**: Solo letras (a–z, A–Z), números (0–9) y puntos (`.`). No se permiten espacios, guiones, guiones bajos ni caracteres especiales.
* **Longitud**: Entre **5 y 20 caracteres**.
* **Unicidad**: El alias debe ser único a nivel de país. Esto no es una restricción de la plataforma, sino un requisito del sistema bancario argentino. Si otro CVU ya utiliza el mismo alias, la solicitud será rechazada.
* **Actualización de un alias**: Para actualizar un alias, llama al mismo endpoint con el nuevo valor una vez transcurrido el período de espera requerido.
* **Límite de cambios**: Una vez establecido o actualizado, un alias no puede volver a cambiarse durante **24 horas**. El alias puede actualizarse un máximo de **10 veces** en total.
* **Activación asincrónica**: El alias se activa en segundo plano. Una respuesta `INPROGRESS` no significa que el alias ya esté activo. Verifica la activación mediante [Obtener estado de la cuenta virtual](https://docs.localpayment.com/es/reference/get-virtual-account-status.md).

**Ejemplos de alias válidos:** `alias.example` · `alias.example2026` · `alias.example.test`

**Ejemplos de alias no válidos:** `alias example` (espacio) · `alias-example` (guion) · `alias_example` (guion bajo) · `alias@example` (arroba)

***

## Establecer alias de cuenta virtual

Establece un alias personalizado para una cuenta virtual activa existente. Esta operación asigna un alias nuevo y también actualiza uno existente. El mismo endpoint gestiona ambos casos.

### Parámetros clave de la solicitud

| Parámetro | Descripción | Requerido |
| - | - | - |
| externalId | El ID externo de la cuenta virtual (parámetro de ruta). | ✅ |
| type | Tipo de alias. Para Argentina, el único valor válido es `C` (Personalizable). | ✅ |
| value | El texto del alias deseado. Solo se permiten letras, números y puntos (`.`). Entre 5 y 20 caracteres. | ✅ |

### Ejemplo de solicitud

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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"
}'
```

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/create-an-alias-to-a-virtual-account.md) en la referencia de la API.

### Respuesta exitosa

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "alias": {
        "type": "C",
        "value": "alias.example"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "Alias creation pending confirmation"
    }
}
```

> [!NOTE]
>
> El estado `INPROGRESS` significa que la solicitud fue recibida y se está procesando de forma asincrónica. El alias **aún no está activo**. Utiliza el endpoint [Obtener estado de la cuenta virtual](https://docs.localpayment.com/es/reference/get-virtual-account-status.md) para confirmar la activación antes de notificar a tus usuarios finales.

### Verificar la activación del alias

Después de recibir una respuesta `INPROGRESS`, consulta la cuenta virtual para confirmar que el alias está activo. Envía una solicitud `GET` al endpoint de estado individual:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId} \
     --header 'Authorization: Bearer <your_access_token>'
```

Una vez que el alias está activo, aparece en `beneficiary.bank.account.alias`:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "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
}
```

Si la configuración del alias falla de forma asincrónica después de una respuesta `INPROGRESS`, el error aparecerá en el arreglo `errors` de esta misma respuesta. Consulta periódicamente el endpoint de estado hasta que `errors` esté vacío y el alias sea visible en `beneficiary.bank.account.alias`.

### Campos de respuesta clave

| Campo | Descripción |
| - | - |
| `externalId` | El ID externo de la cuenta virtual para la que se solicitó el alias. |
| `alias.type` | El tipo de alias de la solicitud (`C`). |
| `alias.value` | El valor del alias de la solicitud. |
| `status.code` | `100`: operación en curso. |
| `status.description` | `INPROGRESS`: la activación del alias se está procesando de forma asincrónica. |

### Respuestas de error

Los siguientes códigos de error se aplican a la respuesta **sincrónica**. Si la respuesta inicial es `INPROGRESS`, la operación fue aceptada, pero aún pueden producirse errores durante el procesamiento asincrónico. Para detectarlos, consulta [Obtener estado de la cuenta virtual](https://docs.localpayment.com/es/reference/get-virtual-account-status.md) y revisa el arreglo `errors`.

| Código | Descripción | Detalle |
| :-: | - | - |
| `776` | `REJECTED` | El alias ya está en uso; por favor, selecciona un alias diferente. |
| `777` | `REJECTED` | El alias no es válido; por favor, introduce un alias válido. |
| `778` | `REJECTED` | El alias no se puede cambiar ahora; debes esperar 24 horas después de la última actualización. |
| `779` | `REJECTED` | Error del sistema al generar el alias. |
| `896` | `REJECTED` | El alias ya está asignado a esta cuenta virtual. |

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "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."
    }
}
```

### Escenarios de errores comunes

| Código | Causa | Solución recomendada |
| :-: | - | - |
| `776` | Alias ya en uso por otro CVU. | Elige un valor de alias diferente y único. |
| `777` | El alias contiene caracteres no válidos, un formato incorrecto o una longitud fuera del rango de 5 a 20 caracteres. | Revisa el campo `value`: solo se permiten letras, números y puntos (`.`), entre 5 y 20 caracteres. |
| `778` | No ha transcurrido el período de cambio de 24 horas desde la última actualización del alias. | Espera al menos 24 horas antes de volver a intentarlo. |
| `779` | Error interno del sistema durante la generación del alias. | Reintenta la solicitud. Si el problema persiste, comunícate con [soporte](mailto:support@localpayment.com). |
| `896` | El alias ya está asignado a esta cuenta virtual. | Utiliza [Obtener estado de la cuenta virtual](https://docs.localpayment.com/es/reference/get-virtual-account-status.md) para verificar el alias que ya está asociado a la cuenta. |

***

## Demo

![](https://mintcdn.com/localpayment-1fee3d41/x0nXcqwNUmbD9R8W/images/docs/7d467db90140ec74c2c8a18e6b4f82d35cebfd2a0e54808f985ea2f228593b48-Demo-Alias-Arg.gif?s=c4dadb3971e23eda32c49653dd86840e)

***

## Próximos pasos

> [card] [Crear cuentas virtuales](https://docs.localpayment.com/es/docs/create-a-virtual-account.md)
>
> Genera nuevas cuentas virtuales que se pueden personalizar con alias.

> [card] [Gestionar el estado de la cuenta virtual](https://docs.localpayment.com/es/docs/get-virtual-account-status.md)
>
> Verifica el estado de las cuentas virtuales y sus alias asociados.

> [card] [Referencia de la API](https://docs.localpayment.com/es/reference/create-an-alias-to-a-virtual-account.md)
>
> Referencia completa de parámetros del endpoint Establecer alias.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.