Dar de alta a tus clientes como comercios

​

Cómo funciona

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

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

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

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

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

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

​

Usa el Merchant ID en todas las demás llamadas

​

Webhooks que debes manejar

​

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.

​

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.

​

Prueba en el sandbox

​

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.