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

# Dar de alta a tus clientes como comercios

> Registra a tus propios clientes como comercios de VelaFi mediante la API, envíalos al proceso de KYC/KYB y activa sus cuentas en moneda local.

Si tu plataforma mueve dinero en nombre de tus propios clientes (personas físicas o empresas), registra a cada cliente como **comercio** dentro de tu cuenta de VelaFi. Cada comercio pasa su propia verificación KYC (personas físicas) o KYB (empresas) y obtiene su propio **Merchant ID (MID)**. Una vez que el comercio está aprobado y sus cuentas de moneda están activas, envías ese MID en cada llamada de pago que hagas para ese cliente.

## Cómo funciona

```mermaid theme={null}
flowchart LR
  A["POST /v2/merchants"] --> B["El cliente completa<br/>la verificación en kycLink"]
  B --> C["GET /v2/merchants<br/>hasta status = 2"]
  C --> D["POST /v2/merchant/accounts<br/>por moneda"]
  D --> E["GET /v2/merchant/accounts<br/>hasta status = 2"]
  E --> F["Opcional: cuentas virtuales"]
  F --> G["Usa el merchantId<br/>en las llamadas de pago"]
```

1. Crea el comercio. VelaFi devuelve un `merchantId` y un `kycLink` alojado.
2. Envía a tu cliente al `kycLink` para que complete el KYC o KYB.
3. Consulta periódicamente el estado del comercio hasta que sea `2` (Normal).
4. Activa una cuenta de moneda (canal) para cada moneda que necesite el cliente.
5. Opcionalmente, crea cuentas virtuales para que cada pagador del cliente tenga sus propios datos de depósito.
6. Usa el `merchantId` en cada orden, pago, transferencia y consulta de ese cliente.

## Antes de empezar

* **Acceso a la API, una clave de API con lista blanca de IP y un token.** Consulta [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md). Todas las llamadas de esta página se hacen desde tu servidor, con el header `X-BH-TOKEN`.
* **Tu propia cuenta aprobada.** Los comercios que creas quedan dentro de tu cuenta de VelaFi. Consulta [Comercios](https://docs.velafi.com/es/docs/merchants.md) para conocer el modelo multicomercio.
* **Los datos del cliente listos.** Decide si cada cliente es `INDIVIDUAL` o `BUSINESS`, y recopila un nombre de comercio y una dirección de correo electrónico para cada uno.
* **Una página a la que regresar a los usuarios.** La envías como `callbackUrl`. En la verificación de personas físicas, VelaFi redirige el navegador del usuario a esta URL cuando termina el flujo alojado.

## Paso a paso

**1. Crea el comercio**

Llama a [Crear un comercio](https://docs.velafi.com/es/api-reference/merchant/create-merchant.md) (`POST /v2/merchants`) con `merchantName`, `email`, `merchantType` (`INDIVIDUAL` o `BUSINESS`) y `callbackUrl`. Envía también `industryType` (y `industryTypeRemark` cuando sea `other`). Para personas físicas, `flow` selecciona el flujo de KYC (`PROFESSIONALS` de forma predeterminada, o `CONSUMERS`), y `languageCode` define el idioma de la página alojada (`en`, `es`, `pt`, `zh`).

```bash theme={null}
curl -X POST https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Example Customer 0001",
    "email": "customer0001@example.com",
    "merchantType": "BUSINESS",
    "industryType": "e-commerce",
    "callbackUrl": "https://your-app.example.com/onboarding/done",
    "languageCode": "en"
  }'
```

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "merchantId": 100001,
    "kycLink": "https://www.velafi.com/verify?velafi_token=abc123"
  }
}
```

Guarda de inmediato el `merchantId` asociado al cliente en tu sistema. El comercio existe a partir de este momento, incluso antes de la verificación.

Rechazos comunes:

| Código | Causa |
| - | - |
| `-5005` | Ya existe un comercio con este `merchantName` en tu cuenta. |
| `-2017` | El `email` ya lo usa un comercio de VelaFi. |
| `-4010` | Un campo no es válido, por ejemplo `merchantType`, `flow` o `email`. `msg` indica el campo. |
| `-5064` | Tu cuenta alcanzó su número máximo de comercios. Contacta a VelaFi. |

> [!WARNING]
>
> Crear un comercio no es idempotente. Si la llamada excede el tiempo de espera, no vuelvas a crear el comercio con datos diferentes. Lista tus comercios filtrando por el `email` que enviaste (consulta el paso 3) para saber si se creó.

**2. Envía al cliente al enlace de verificación**

Redirige el navegador del cliente al `kycLink`, o ábrelo en un iframe dentro de tu app. Las personas físicas completan el KYC; las empresas completan el KYB. Consulta [Crear un comercio](https://docs.velafi.com/es/docs/guides/creating-merchant.md) para ver ambas opciones de visualización.

El enlace tiene una vigencia limitada. Si el cliente no terminó, o el enlace expiró, obtén uno nuevo llamando otra vez a `POST /v2/merchants` con el `merchantId` existente, el mismo `merchantType` que usaste al crearlo y `callbackUrl`:

```json theme={null}
{
  "merchantId": 100001,
  "merchantType": "BUSINESS",
  "callbackUrl": "https://your-app.example.com/onboarding/done",
  "languageCode": "en"
}
```

Esto no crea un segundo comercio. Falla con `-5062` mientras la verificación del comercio está en revisión y con `-5063` una vez que fue aprobada.

> [!NOTE]
>
> Llegar a tu `callbackUrl` solo significa que el cliente salió del flujo alojado. No significa que haya sido aprobado. Revisa siempre el estado en el siguiente paso.

**3. Revisa el estado del comercio**

Llama a [Listar comercios](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchants.md) (`GET /v2/merchants`) y lee `status` y `rejectReason`. Envía `status=-1`: sin él, la lista devuelve solo los comercios aprobados. Filtra con `email` o `merchantName` para encontrar un comercio.

```bash theme={null}
curl -G https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "status=-1" \
  --data-urlencode "email=customer0001@example.com"
```

| `status` | Significado | Qué hacer |
| - | - | - |
| `4` | Incompleta | El cliente no ha terminado el flujo alojado. Envíale un nuevo enlace (paso 2). |
| `1` | En autenticación | En revisión. Sigue consultando. |
| `2` | Normal | Aprobado. Continúa con el paso 4. |
| `3` | Autenticación fallida | Rechazado. Lee `rejectReason`. Puedes solicitar un nuevo enlace para volver a enviarla. |

No hay webhook para la verificación de comercios. Consulta con un intervalo moderado, por ejemplo, cada pocos minutos mientras el cliente se está dando de alta y con menos frecuencia después.

**4. Activa las cuentas de moneda**

Para cada moneda que necesite el cliente, llama a `POST /v2/merchant/accounts` con `merchantId`, `fiat` y `trench` (el nombre del canal), además del `fieldList` del canal. La solicitud varía según el tipo de comercio:

* Personas físicas: [Activar la cuenta de un comercio persona física](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-individual.md)
* Empresas: [Activar la cuenta de un comercio empresa](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-business.md)

```bash 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"
  }'
```

Maneja el `status` devuelto:

| `status` | Significado | Qué hacer |
| - | - | - |
| `0` con `verifyLink` | Comercios de tipo empresa: el canal necesita una verificación adicional de la empresa. | Envía a la empresa al `verifyLink`. Después de que VelaFi la aprueba, el canal se abre sin otra llamada. |
| `1` | Pendiente. El proveedor está abriendo la cuenta. | Consulta periódicamente [Listar cuentas de comercio](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchant-accounts.md). |
| `2` | Activa. | Listo. |
| `3` | Fallida. | Lee `failReason`. |
| `4` con `verifyLink` | Incompleta. Por ejemplo, USD/EUR mediante Lead Bank requiere un contrato. | Envía al comercio al `verifyLink`. |

Después, consulta `GET /v2/merchant/accounts?merchantId=100001` hasta que el canal muestre `status: 2`. Cada registro también devuelve el `paymentId` del canal, que necesitas para cuentas virtuales, pagos y órdenes.

Algunos canales tienen requisitos adicionales. BRL Pix - Woovi requiere primero una prueba de vida para personas físicas ([Obtener la URL de prueba de vida de Woovi](https://docs.velafi.com/es/api-reference/merchant/get-woovi-liveness-url.md)) y los datos completos de la empresa y de los UBO para empresas. Los documentos se deben subir con [Subir un archivo](https://docs.velafi.com/es/api-reference/basic-configuration/upload-file.md). Consulta [Activar la cuenta de un comercio](https://docs.velafi.com/es/docs/guides/activating-merchant-account.md) para ver todos los canales.

Rechazos comunes: `-5073` (el comercio todavía no ha pasado el KYC), `-5074` (ya está activa), `-5062` (la activación ya está pendiente), `-5079` (sin permiso de activación para este canal), `-4010` (falta un campo obligatorio de `fieldList` o no es válido).

**5. Opcional: crea cuentas virtuales**

Si el cliente cobra a muchos pagadores, dale a cada pagador sus propios datos de depósito con [Crear cuentas virtuales](https://docs.velafi.com/es/api-reference/merchant/create-multiple-virtual-account.md) (`POST /v2/merchant/virtual/accounts`). Envía `merchantId`, `fiat`, el `paymentId` del canal y un `alias` de letras y dígitos. Las cuentas virtuales están disponibles para MXN, ARS, BRL y COP, y la cuenta de moneda ya debe estar activa.

Lee los datos de depósito con [Listar cuentas virtuales](https://docs.velafi.com/es/api-reference/merchant/get-multiple-virtual-account.md). Los depósitos a una cuenta virtual llevan su alias como `depositAlias`. Consulta [Cobrar pagos locales con cuentas virtuales](https://docs.velafi.com/es/docs/use-cases/collect-with-virtual-accounts.md) para ver el flujo de cobro completo.

## Usa el Merchant ID en todas las demás llamadas

El `merchantId` determina el saldo, los límites y las cuentas de quién usa una llamada. Envía el MID del cliente, no el tuyo, en cada llamada que hagas para ese cliente:

| Llamada | Campo |
| - | - |
| Órdenes de on-ramp y off-ramp (`POST /v2/order/fiat_to_crypto`, `POST /v2/order/crypto_to_fiat`) | `merchantId` |
| Órdenes de pagos globales (`POST /v2/order/fiat_to_fiat`) | `onRampMerchantId`, `offRampMerchantId` |
| Pagos desde el saldo fiat (`POST /v2/merchant/claimfunds`) | `merchantId` |
| Transferencias entre comercios (`POST /v2/merchant/transfer`) | `fromMerchantId`, `toMerchantId` |
| Beneficiarios (`POST /v2/payments`) | `merchantId` del comercio a cuya cuenta de moneda pertenece el beneficiario. Envíalo siempre: sin él, agregar un beneficiario para un método de pago automático falla. |
| Retiros de cripto y direcciones de depósito | `merchantId` |
| Datos de depósito, registros de fondeo, flujos fiat, saldos | Filtro `merchantId` |

Mantén una correspondencia uno a uno entre tu ID de cliente y el MID de VelaFi, y nunca permitas que un valor proporcionado por el cliente elija el MID.

## Webhooks que debes manejar

La verificación de comercios y la activación de canales no tienen webhook. Consulta periódicamente `GET /v2/merchants` y `GET /v2/merchant/accounts` como se describe arriba.

Los webhooks se registran por cuenta de VelaFi, no por comercio: un registro por tipo de evento recibe los eventos de todos tus comercios. Los eventos de órdenes, fondeo, retiros de cripto y pagos con stablecoin llevan un `merchantId`, así que enrútalos con él. Para los eventos que no lo llevan, busca el registro por su ID. Consulta [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md).

## Maneja las fallas

* **Verificación rechazada (`status: 3`).** Muestra `rejectReason` a tu cliente y después solicita un nuevo enlace con el mismo `merchantId` y `merchantType`.
* **El cliente abandona el flujo (`status: 4`).** Envía un recordatorio con un enlace nuevo. No crees un nuevo comercio; el nombre y el correo electrónico ya los ocupa el primero.
* **Activación fallida (`status: 3`).** Lee `failReason` en la respuesta de la activación o en Listar cuentas de comercio. Corrige los datos de `fieldList` o contacta a VelaFi.
* **Activación pendiente durante mucho tiempo.** Los canales pendientes dependen del proveedor. Sigue consultando y contacta a VelaFi si el canal no se activa.
* **Timeouts y errores de resultado desconocido** (`-1001`, `-1006`, `-1007`). Es posible que el comercio o el canal se hayan creado. Verifica con Listar comercios o Listar cuentas de comercio antes de volver a llamar. Consulta [Códigos de error](https://docs.velafi.com/es/docs/error-codes.md#outcome-unknown-check-before-you-retry).

## Concilia

* `GET /v2/merchants` con `status=-1` es la fuente de verdad del estado de verificación y del uso de los límites diarios y mensuales de cada comercio.
* `GET /v2/merchant/accounts` es la fuente de verdad de qué canales están activos, su `paymentId`, su saldo y sus límites mensuales de compra/venta.

Ejecuta un proceso periódico que compare tus registros de clientes con ambas listas, para que ningún cliente se quede atorado en un estado que tu sistema desconoce.

## Prueba en el sandbox

Tu cuenta de sandbox incluye comercios de prueba preconfigurados, y en el sandbox no se realiza ningún KYC/KYB real. Usa esos comercios para probar los resultados de activación, las cuentas virtuales y los flujos de pago posteriores. Escribe tu manejo de estados contra cada código de estado de las tablas de arriba, porque no puedes hacer que un revisor real apruebe o rechace un comercio de sandbox. Consulta [Sandbox](https://docs.velafi.com/es/docs/sandbox.md).

## Lista de verificación para salir a producción

* Guarda el `merchantId` en cuanto `POST /v2/merchants` responda, y vincúlalo uno a uno con tu cliente.
* Maneja cada estado del comercio (`1`, `2`, `3`, `4`) y cada estado de activación (`0` a `4`), incluidas las redirecciones a `verifyLink`.
* Consulta con `status=-1`, para que los comercios que todavía no están aprobados no falten en tus resultados.
* Vuelve a solicitar los enlaces expirados con el `merchantId` y el `merchantType` existentes en lugar de crear un comercio duplicado.
* Espera a que el canal muestre `status: 2` antes de crear cuentas virtuales o enviar pagos en esa moneda.
* Envía el MID del cliente en cada llamada posterior y enruta los eventos de webhook por `merchantId`.

Después, recorre la [lista de verificación para salir a producción](https://docs.velafi.com/es/docs/use-cases/go-live-checklist.md) compartida.


## Related topics

- [Casos de uso principales](https://docs.velafi.com/es/docs/use-cases/overview.md)
- [Agent Skills](https://docs.velafi.com/es/docs/developer-tools/agent-skills.md)
- [Lista de verificación para salir a producción](https://docs.velafi.com/es/docs/use-cases/go-live-checklist.md)
- [Comercios](https://docs.velafi.com/es/docs/merchants.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.