Crear un comercio

Toda entidad que envíe o reciba dinero a través de VelaFi debe estar registrada como comercio y aprobar la verificación de identidad. VelaFi usa este proceso para cumplir con las regulaciones de Conoce a tu Cliente (KYC) y Conoce tu Negocio (KYB). Una vez completada la verificación, la plataforma asigna a la entidad un Merchant ID (MID) único. Debes incluir este MID en cada llamada posterior a la API relacionada con transacciones, administración de la cuenta y liquidaciones.

Por qué se requieren los comercios

VelaFi opera dentro de un ecosistema financiero regulado. Cada registro de comercio vincula a una persona o empresa real con su actividad de on-ramp, off-ramp y pagos globales. La revisión de cumplimiento garantiza que todas las partes cumplan con los estándares de prevención de lavado de dinero (AML) y de combate al financiamiento del terrorismo (CFT) antes de que se mueva cualquier fondo.

Crear un comercio

Envía una solicitud POST a /v2/merchants para registrar un nuevo comercio persona física o empresa e iniciar el flujo de verificación. Endpoint

POST https://api.velafi.com/v2/merchants

Headers

X-BH-TOKEN: <your-token>
Content-Type: application/json

Parámetros de la solicitud

string

requerido

Nombre completo o razón social del comercio. Debe ser único dentro de tu cuenta.

string

requerido

Correo electrónico del comercio. Debe ser único dentro de tu cuenta.

string

requerido

Tipo de entidad del comercio. Valores aceptados: INDIVIDUAL, BUSINESS.

string

requerido

URL a la que VelaFi llama cuando termina el proceso de KYC/KYB (con éxito o con falla). VelaFi envía una notificación POST a esta URL.

string

Sector de la industria del comercio. Obligatorio cuando merchantType es BUSINESS. Valores aceptados: payment_psp, fintech, lending, fx_or_otc, e-commerce, gaming_or_entertainment, crypto_or_web3, supply_chain, import_or_export, payroll_or_hr, media_or_advertising, remittance_or_money_transfer, treasury_or_asset_management, wholesale_or_b2b_marketplace, logistics_and_courier, digital_content_or_streaming, travel_or_booking, online_marketplace, investment_and_crowdfunding, real_estate_and_proptech, accounting_or_billing, freelancer_platform, saas_or_api, online_education, outsourcing_agency, other.

string

Flujo de KYC, solo para comercios INDIVIDUAL. Valores aceptados: PROFESSIONALS (predeterminado), CONSUMERS.

string

Idioma de la interfaz de verificación KYC/KYB. Valores aceptados: en (predeterminado), es, pt, zh.

string

Nota opcional de texto libre para adjuntar a este registro de comercio.

string

Obligatorio cuando industryType es other. Proporciona una descripción breve de la industria real del comercio.

Ejemplo de solicitud

curl -X POST https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Acme Payments Ltd",
    "email": "payments@acme.com",
    "merchantType": "BUSINESS",
    "callbackUrl": "https://acme.com/webhooks/kyc",
    "languageCode": "en",
    "industryType": "fintech",
    "remark": "Primary merchant account"
  }'

{
  "merchantName": "Acme Payments Ltd",
  "email": "payments@acme.com",
  "merchantType": "BUSINESS",
  "callbackUrl": "https://acme.com/webhooks/kyc",
  "languageCode": "en",
  "industryType": "fintech",
  "remark": "Primary merchant account"
}

Campos de la respuesta

number

Código de respuesta. 200 indica éxito.

string

Mensaje de resultado legible, por ejemplo SUCCESS.

object

Mostrar campos de data

number

Merchant ID (MID) único asignado a este comercio. Guarda este valor: lo necesitas para todas las llamadas posteriores a la API.

string

URL que lleva a la página segura de verificación KYC/KYB de VelaFi. Redirige a tu usuario a esta URL o insértala en un iframe.

Ejemplo de respuesta

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

Completar la verificación KYC/KYB

Después de una llamada exitosa a POST /v2/merchants, dirige a tu usuario a la URL de kycLink para completar la verificación de identidad. Tienes dos opciones de integración:

Modo de redirección
Modo incrustado (iframe)

Redirige el navegador del usuario directamente a la URL de kycLink. Es la integración más sencilla: el usuario completa la verificación en la página alojada por VelaFi y regresa a tu callbackUrl al terminar.

window.location.href = data.kycLink;

Inserta la URL de kycLink en un <iframe> dentro de tu aplicación para ofrecer una experiencia fluida dentro de la app.

<iframe
  src="https://www.velafi.com/verify?velafi_token=abc123"
  width="100%"
  height="700"
  title="Identity Verification"
/>

Usa solo componentes compatibles con Mintlify en las páginas MDX. El fragmento de iframe anterior es para el código frontend de tu aplicación, no para esta página de documentación.

La URL de kycLink puede expirar después de un periodo corto, según la sesión y la configuración. Asegúrate de que tu usuario la abra poco después de la llamada a la API.

Volver a solicitar el enlace de KYC para un comercio no verificado

Si un comercio no completó la verificación en la sesión inicial (por ejemplo, porque el enlace expiró o el usuario cerró el navegador), puedes solicitar un nuevo kycLink sin crear un registro de comercio duplicado. Envía el merchantId existente en lugar de todos los datos del comercio:

{
  "merchantId": 100001,
  "callbackUrl": "https://acme.com/webhooks/kyc",
  "languageCode": "en"
}

La respuesta contiene un kycLink nuevo al que puedes volver a redirigir al usuario.

Modos de administración de comercios

Administración de múltiples comercios

Una vez que la cuenta de tu comercio principal haya aprobado la verificación KYB, puedes crear y administrar subcomercios, ya sean personas físicas o empresas, dentro de tu cuenta. Esto permite una administración jerárquica de comercios con control de acceso basado en roles y configuración por comercio.Los casos de uso comunes incluyen:

Agregadores que gestionan pagos en nombre de varios clientes
Plataformas que ofrecen infraestructura de pagos a sus propios comercios
Operadores de marketplaces que gestionan el cumplimiento y las liquidaciones a nivel de comercio

Cada subcomercio pasa por su propio flujo de KYC/KYB y recibe su propio MID.

Modo Reliance (instituciones financieras con licencia)

Si tu organización es una institución financiera con licencia, puedes solicitar que se habilite el modo Reliance. En este modo:

Asumes la responsabilidad del onboarding de comercios, la revisión continua y el monitoreo de cumplimiento.
VelaFi no interviene en tu flujo de onboarding de comercios.
VelaFi sigue proporcionando la infraestructura técnica, los rieles de liquidación y el soporte regulatorio.

El modo Reliance requiere una revisión de cumplimiento adicional por parte del equipo de Cumplimiento de VelaFi. Más información sobre el proceso de solicitud del modo Reliance.

Primeros pasos

Conceptos clave

Guías

Referencia

Crear un comercio

Por qué se requieren los comercios