/v2/user/account. Si quieres explorar la API sin riesgo antes de salir a producción, el último paso te lleva al entorno sandbox.
1
Crea tu cuenta de VelaFi
Ve a velafi.com/signup y completa el formulario de registro. Sigue las instrucciones en pantalla para verificar tu correo electrónico y terminar de configurar tu cuenta.Después del registro, VelaFi te asigna un ID de usuario (UID) único. Este UID es el identificador de nivel superior de todos los comercios, claves de API y transacciones asociados a tu cuenta. Tenlo a la mano: lo verás en todo el panel y en las respuestas de la API.
2
Crea un comercio y completa el KYC/KYB
VelaFi requiere que toda operación de pago se realice bajo una entidad de comercio verificada. Un comercio puede representar tu propio negocio o a un cliente individual que estés incorporando.Para crear un comercio:
- En el panel, abre la sección Merchants y haz clic en Create Merchant.
- Selecciona el tipo de entidad, Individual (persona física) o Business (empresa), y llena los datos requeridos.
- Sube los documentos de cumplimiento solicitados para el KYC (personas físicas) o el KYB (empresas).
- Envía el formulario y espera la aprobación del equipo de cumplimiento de VelaFi.
Para ver el proceso completo de creación del comercio y los requisitos de documentos, consulta la guía Crear tu comercio.
3
Genera tu clave de API
Con tu cuenta activa, ya puedes crear una clave de API desde el panel de VelaFi.
- Inicia sesión y abre Gestión de API.
- Haz clic en Crear clave de API.
- Si tu cuenta todavía no tiene activada la autenticación de dos factores (2FA), el sistema te pedirá configurarla antes de continuar. Completa la configuración de 2FA: es obligatoria para generar claves.
- Escribe una nota (de 1 a 30 caracteres) para identificar la clave (por ejemplo,
production-backend). - Haz clic en Continuar e ingresa tu código 2FA. La ventana de confirmación muestra tu clave de API y tu secreto de API.
-1023).Cada solicitud a la API se autentica enviando un token, obtenido con esta clave y este secreto desde GET /v2/token/generate, en el encabezado X-BH-TOKEN:4
Activa tu acceso a la API
Generar una clave de API no habilita automáticamente el acceso a la API en tu cuenta. Debes contactar al equipo de soporte de VelaFi para completar la activación.Envía un correo a contact@velafi.com con el UID de tu cuenta y una breve descripción del caso de uso que planeas. El equipo te confirmará por correo cuando el acceso a la API esté activo en tu cuenta.
Mientras el acceso a la API no esté activo, las solicitudes de token fallan con el código
-5033.5
Haz tu primera llamada a la API
Una vez activada tu cuenta, obtén un token y llama al endpoint de detalles de la cuenta para verificar tu configuración.Una respuesta exitosa devuelve
"code": 200 y "msg": "SUCCESS", con los detalles de tu cuenta en data. Consulta Obtener detalles de la cuenta para ver los campos.Si una llamada falla, revisa el code negativo en el cuerpo de la respuesta:-5033en la solicitud de token: el acceso a la API todavía no está habilitado en tu cuenta. Contacta a VelaFi.-1023en la solicitud de token: la clave de API no tiene lista blanca de IP.-2015en la solicitud de token: la solicitud vino de una dirección IP que no está en la lista blanca de la clave, o la clave o tu cuenta están deshabilitadas.-1022: la firma es incorrecta o la clave de API no existe (solicitud de token), o el token es inválido o expiró (llamada a la API).-2019en la llamada a la API: la solicitud vino de una dirección IP que no está en la lista blanca de la clave.
6
Prueba el sandbox
Antes de construir flujos de producción, usa el sandbox de VelaFi para probar tu integración con datos simulados, sin riesgo para fondos reales. El sandbox replica la API de producción en una URL base distinta y requiere credenciales separadas que proporciona el equipo de VelaFi.
- URL base del sandbox:
https://api-test.velafi.com - Credenciales: escribe a contact@velafi.com para solicitar credenciales de sandbox; no se requiere KYC ni crear una clave de API.
Siguientes pasos
Entorno sandbox
Prueba con datos simulados antes de tocar producción.
On-ramp: fiat → cripto
Construye de principio a fin tu primer flujo de órdenes fiat a cripto.
Off-ramp: cripto → fiat
Convierte saldos en cripto y entrega fiat a las cuentas de los beneficiarios.
Referencia de la API
Explora el catálogo completo de endpoints con sus parámetros y esquemas de respuesta.