> ## 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.

# Activar la cuenta de un comercio persona física

> Activa un canal de pago fiat para un comercio persona física, con soporte para MXN, ARS, COP, BRL, PEN, USD y EUR mediante proveedores de pago locales.

Usa este endpoint para activar uno o más canales de pago fiat para un comercio persona física. Una vez activado, el comercio recibe credenciales bancarias dedicadas (por ejemplo, una CLABE para México o un CVU para Argentina) y puede recibir transferencias bancarias entrantes que VelaFi concilia automáticamente con su saldo. Cada combinación de moneda y proveedor de pago requiere una solicitud de activación por separado.

> [!NOTE]
>
> Todas las solicitudes deben incluir el header `X-BH-TOKEN` y `Content-Type: application/json`.

## Endpoint

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

## Campos principales de la solicitud

**merchantId** `string` *required*

El ID del comercio que se va a activar.

**fiat** `string` *required*

Moneda fiat de destino. Valores admitidos: `MXN`, `ARS`, `COP`, `BRL`, `PEN`, `EUR`, `USD`.

**trench** `string` *required*

Identificador del proveedor de pago o del tipo de cuenta. Debe coincidir con uno de los valores admitidos para el `fiat` elegido (consulta los ejemplos más abajo).

**callbackUri** `string`

URL de redirección que se muestra después de que el comercio acepta un acuerdo de cumplimiento. La usan los canales de Lead Bank; si la omites, se usa una URL de redirección predeterminada de VelaFi.

**fieldList** `object`

Campos específicos del canal. El contenido varía según `fiat` y `trench`. Consulta los ejemplos por moneda más abajo.

## Campos de la respuesta

**code** `number`

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

**msg** `string`

Mensaje de estado legible, por ejemplo `SUCCESS`.

**data** `object`

**campos de data**

**fiat** `string`

La moneda fiat que se activó.

**status** `number`

Estado del canal: `0` = inicializado, `1` = pendiente, `2` = activo, `3` = fallido (consulta `failReason`), `4` = incompleto (el comercio debe completar un paso en `verifyLink`). El valor que recibes depende del canal. Consulta [Resultados de la activación](#activation-outcomes).

**verifyLink** `string`

Para los canales USD/EUR que requieren un paso adicional de aceptación de acuerdo, esta URL redirige al comercio a la página del acuerdo.

**failReason** `string`

Describe por qué falló la activación, si aplica.

## Ejemplos por moneda

> [tab] MXN
>
> **MXN — SPEI mediante Finco Pay** (`trench: "CLABE - FINCO PAY"`)
>
> ```bash cURL theme={null}
> curl -X POST https://api.velafi.com/v2/merchant/accounts \
>   -H "X-BH-TOKEN: YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "merchantId": "100001",
>     "fiat": "MXN",
>     "trench": "CLABE - FINCO PAY",
>     "fieldList": { "alias": "arturo_alias" }
>   }'
> ```
>
> **MXN — SPEI mediante Tesored** (`trench: "CLABE - TESORED"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "MXN",
>   "trench": "CLABE - TESORED",
>   "fieldList": { "alias": "arturo_alias" }
> }
> ```

> [tab] ARS
>
> **ARS — CVU mediante Momentum** (`trench: "CVU - Momentum"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "CVU - Momentum",
>   "fieldList": {
>     "email": "arturo@example.com",
>     "cuit": "30000000001",
>     "name": "EXAMPLE COMPANY SA",
>     "alias": "example.alias"
>   }
> }
> ```
>
> **ARS — Transferencia QR 3.0** (`trench: "QR Argentina"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "QR Argentina",
>   "fieldList": { "cuit": "123456789" }
> }
> ```

> [tab] COP
>
> **COP — PSE / ACH / Bre-B** (`trench: "COP Account"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "COP",
>   "trench": "COP Account",
>   "fieldList": { "alias": "example.alias" }
> }
> ```

> [tab] BRL
>
> **BRL — Pix mediante Genial** (`trench: "BANCO GENIAL"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "BRL",
>   "trench": "BANCO GENIAL"
> }
> ```
>
> **BRL — Pix mediante Woovi** (`trench: "Pix - Woovi"`) — requiere información personal completa y una prueba de vida completada
>
> Sigue este orden:
>
> 1. Llama a [Obtener la URL de prueba de vida de Woovi](https://docs.velafi.com/es/api-reference/merchant/get-woovi-liveness-url.md) y pide al comercio que complete la prueba de vida en el `livenessUrl` devuelto.
> 2. Envía la solicitud de activación de abajo. Si la prueba de vida no está completa, la solicitud falla con el código de error `-5059`.
> 3. La respuesta devuelve `status: 1` (pendiente). Consulta periódicamente [Listar cuentas del comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md) hasta que el `status` del canal sea `2`.
>
> Reglas de los campos: `govIdFrontUrl` y `govIdBackUrl` son obligatorios y deben ser valores `fileUrl` devueltos por [Subir archivo](https://docs.velafi.com/es/api-reference/basic-configuration/upload-file.md). Las URL públicas se rechazan. `taxIdentificationNumber` solo puede contener letras y dígitos. `dateOfBirth` usa el formato `yyyy-MM-dd` y la persona debe tener al menos 18 años. `idType` es `1` (documento de identidad), `2` (licencia de conducir) o `3` (pasaporte). `countryStateCode` es el código de país de dos letras, un guion y el código del estado, por ejemplo `BR-SP`.
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "BRL",
>   "trench": "Pix - Woovi",
>   "fieldList": {
>     "personalInfo": {
>       "firstName": "MARIA",
>       "lastName": "EXEMPLO",
>       "email": "maria@example.com",
>       "taxIdentificationNumber": "00000000001",
>       "nationality": "BR",
>       "dateOfBirth": "1990-01-01",
>       "street1": "Rua das Flores 123",
>       "city": "São Paulo",
>       "countryStateCode": "BR-SP",
>       "postcode": "01310-100",
>       "idType": "1",
>       "govIdCountryAbbr": "BR",
>       "govIdFrontUrl": "100001/00000000-0000-0000-0000-000000000001.png",
>       "govIdBackUrl": "100001/00000000-0000-0000-0000-000000000004.png"
>     }
>   }
> }
> ```

> [tab] PEN
>
> **PEN — Transferencia bancaria** (`trench: "PEN Account"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "PEN",
>   "trench": "PEN Account",
>   "fieldList": {
>     "customerIdentificationType": "00",
>     "customerIdentification": "12345678",
>     "customerName": "Tom",
>     "lastName": "Garcia",
>     "customerEmail": "tom@example.com",
>     "customerPhone": "975728895"
>   }
> }
> ```

> [tab] USD/EUR
>
> **USD/EUR — Lead Bank** (`trench: "Lead Bank"`)
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "EUR",
>   "trench": "Lead Bank",
>   "callbackUri": "https://your-app.com/agreement-callback",
>   "fieldList": {
>     "email": "arturo@example.com",
>     "firstName": "Arturo",
>     "lastName": "Garcia"
>   }
> }
> ```
>
> **Multimoneda — Circle Payment Network** (`trench: "Circle Payment Network"`)
>
> Admite: USD, HKD, EUR, SGD, NGN. Solo pagos.
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "USD",
>   "trench": "Circle Payment Network",
>   "fieldList": {
>     "accountName": "Tom",
>     "nationality": "HK",
>     "idNumber": "123456",
>     "countryStateCode": "HK-HK",
>     "city": "Hong Kong",
>     "street": "789 Finance Street",
>     "postalCode": "123456",
>     "dateOfBirth": "1990-01-01",
>     "phoneNumber": "123456"
>   }
> }
> ```

## Resultados de la activación

### Estado devuelto en una primera activación

La mayoría de los canales locales devuelven `status: 1` (pendiente) y pasan a `2` (activo) una vez que el proveedor termina de abrir la cuenta. Revisa el canal más tarde con [Listar cuentas del comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md).

| Trench | Estado devuelto | Significado |
| - | - | - |
| `CLABE - FINCO PAY`, `CLABE - TESORED` (MXN) | `1` | Pendiente. La cuenta se está abriendo. |
| `CVU - Momentum`, `QR Argentina` (ARS) | `1` | Pendiente |
| `COP Account` (COP) | `1` | Pendiente |
| `BANCO GENIAL` (BRL) | `1` | Pendiente |
| `Pix - Woovi` (BRL, proporcionado por Avenia) | `1` | Pendiente. Solo se devuelve después de que el comercio completó la prueba de vida. |
| `PEN Account` (PEN) | `2` | Activo de inmediato |
| `Circle Payment Network` | `2` | Activo de inmediato |
| `Lead Bank` (USD/EUR) | `4` | Incompleto. Envía al comercio a `verifyLink` para aceptar el acuerdo y completar la verificación. |

### Lead Bank: volver a llamar

Si vuelves a llamar a este endpoint para Lead Bank cuando el comercio ya tiene una verificación de Lead Bank:

| Situación | Estado devuelto |
| - | - |
| La verificación no ha terminado y todavía se puede reanudar | `4` con un nuevo `verifyLink` |
| La verificación no fue rechazada y no es necesario rehacerla | `3` con `failReason` `Kyc is on processing or completed` |

### Errores en lugar de un estado

En estos casos se devuelve un código de error en lugar de un `status`:

| Código | Cuándo |
| - | - |
| `-5074` | El canal ya está activo para este comercio. |
| `-5062` | La activación del canal ya está pendiente. |
| `-5076` | El canal fue cerrado. |
| `-5078` | El canal fue deshabilitado. |
| `-5079` | El comercio no tiene permiso de activación para este canal. |
| `-5073` | El comercio no ha aprobado el KYC. |
| `-5077` | El comercio fue deshabilitado. |
| `-4010` | Falta un campo obligatorio de `fieldList` o no es válido. |
| `-5059` | El proveedor no pudo registrar al comercio (`msg`: `Merchant registration failure.`). Para `Pix - Woovi`, el mismo código significa que la prueba de vida no está completa (`msg`: `Please first pass the Liveness authentication`). |
| `-5066` | Solo `Pix - Woovi`: la cuenta ya está en revisión. |
| `-5067` | Solo `Pix - Woovi`: la cuenta ya está activa. |

Cuando el proveedor rechaza el registro (`-5059`), el canal se registra como fallido (`3`) y puedes verlo con [Listar cuentas del comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md).

## Ejemplos de respuesta

```json MXN / ARS / COP / BRL (pending) theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "MXN",
    "status": 1,
    "failReason": ""
  }
}
```

```json PEN / Circle Payment Network (active) theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "PEN",
    "status": 2,
    "failReason": ""
  }
}
```

```json USD / EUR (agreement required) theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "EUR",
    "status": 4,
    "verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08",
    "failReason": ""
  }
}
```

> [!WARNING]
>
> Para BRL Woovi, el comercio debe completar la prueba de vida de Woovi **antes** de que llames a este endpoint (consulta [Obtener la URL de prueba de vida de Woovi](https://docs.velafi.com/es/api-reference/merchant/get-woovi-liveness-url.md)). Sin ella, la solicitud falla con el código de error `-5059`. Para USD/EUR con Lead Bank, la respuesta devuelve `status: 4` con un `verifyLink`. Dirige al comercio a ese enlace para completar los pasos restantes.


## Related topics

- [Activar la cuenta de un comercio](https://docs.velafi.com/es/docs/guides/activating-merchant-account.md)
- [Activar la cuenta de un comercio empresa](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-business.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Comercios](https://docs.velafi.com/es/docs/merchants.md)
- [Obtener la URL de prueba de vida de Woovi](https://docs.velafi.com/es/api-reference/merchant/get-woovi-liveness-url.md)


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