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

# Crear cuentas virtuales

> Crea una subcuenta virtual adicional para un comercio en un canal de pago fiat ya activado, para enrutar fondos por alias.

Usa este endpoint para crear cuentas virtuales adicionales en un canal de pago fiat ya activado. Cada cuenta virtual recibe sus propios datos bancarios únicos (p. ej., una CLABE o un CVU dedicado), para que puedas enrutar y conciliar fondos por alias. La cuenta en la moneda fiat correspondiente debe estar activa antes de que puedas crear cuentas virtuales. Las monedas admitidas son MXN, ARS, BRL y COP.

> [!NOTE]
>
> Todas las solicitudes deben incluir el header `X-BH-TOKEN` y `Content-Type: application/json`. El valor de `alias` solo puede contener letras y números.

## Endpoint

`POST https://api.velafi.com/v2/merchant/virtual/accounts`

## Parámetros de la solicitud

**merchantId** `number` *required*

ID del comercio para el que se crea la cuenta virtual.

**fiat** `string` *required*

Moneda fiat de la cuenta virtual. Valores admitidos: `MXN`, `ARS`, `BRL`, `COP`.

**paymentId** `number` *required*

ID del canal de pago que se usará. Correspondencias admitidas:

* `72` o `105`: MXN
* `63`: ARS
* `68` (ACH automático) o `69` (Bre-B): COP
* `90` o `92`: BRL

**alias** `string` *required*

Un alias único para esta cuenta virtual, formado solo por letras y dígitos (hasta 64 caracteres). Para COP (`68`, `69`), el alias debe tener de 6 a 21 letras mayúsculas o dígitos. `default` (en cualquier combinación de mayúsculas y minúsculas) está reservado y no se puede usar. La solicitud se rechaza si el mismo comercio ya tiene una cuenta virtual pendiente o activa con el mismo `fiat`, `paymentId` y `alias`.

## Campos de la respuesta

**code** `number`

Código de respuesta tipo HTTP. `200` indica éxito.

**msg** `string`

Mensaje de estado legible, p. ej. `SUCCESS`.

**data** `object`

**Campos de data**

**fiat** `string`

Moneda fiat de la cuenta virtual recién creada.

**status** `number`

Estado de la cuenta virtual: `1` = pendiente, `2` = activa, `3` = fallida. Cuando la creación es exitosa, las cuentas virtuales de ARS (`63`) devuelven `2` de inmediato y los demás canales devuelven `1` mientras se configura la cuenta.

## Ejemplo

```bash cURL theme={null}
curl -X POST https://api.velafi.com/v2/merchant/virtual/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 151209,
    "fiat": "MXN",
    "paymentId": 105,
    "alias": "store001"
  }'
```

```json Respuesta theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "MXN",
    "status": 1
  }
}
```

> [!TIP]
>
> Usa alias distintos para asignar cuentas virtuales a usuarios, tiendas o centros de costos individuales dentro de tu plataforma. El alias es permanente: crea una nueva cuenta virtual si necesitas un identificador diferente.


## Related topics

- [Listar cuentas virtuales](https://docs.velafi.com/es/api-reference/merchant/get-multiple-virtual-account.md)
- [Crear una cuenta](https://docs.velafi.com/es/docs/guides/creating-account.md)
- [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Crear un comercio](https://docs.velafi.com/es/docs/guides/creating-merchant.md)


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