Saltar al contenido principal
En resumen
Las Cuentas Virtuales permiten que sus clientes reciban moneda fiat mediante transferencias bancarias tradicionales, que se convierten automáticamente en stablecoins en la blockchain. El flujo v2 descubre los activos y las monedas disponibles para su wallet, devuelve un esquema que describe exactamente lo que requiere cada corredor, y crea cuentas virtuales vinculadas a una master wallet o child address en múltiples monedas y stablecoins.
Cuentas Virtuales
Los requisitos v2 devuelven un JSON Schema que describe la información que necesita un corredor. Cuando additionalDataRequired es true, utilice la guía de Formularios dinámicos para recopilar, validar y enviar los campos como additionalData. El flujo v1 está disponible en la pestaña v1 · Legacy, pero ya no se recomienda.

Requisitos previos

Antes de utilizar las Cuentas Virtuales, asegúrese de contar con:
1

Clave de API

Obtenga su clave de API desde el Dashboard de Blockradar. Diríjase a Developers para generar una.
2

Wallet creada

Cree una wallet mediante la guía Crear una Master Wallet o desde el dashboard. Necesitará el walletId para las operaciones con cuentas virtuales.
3

Cumplimiento aprobado

Complete el proceso de Diligencia Debida en el Dashboard: My Wallets → Settings → Compliance. Los requisitos de cumplimiento y los procesos de aprobación varían según la región, por lo que solo necesita completar los correspondientes a los rieles locales que utilice su producto.
4

Función habilitada

Solicite la activación de la función de cuentas virtuales tras la aprobación de cumplimiento. Contacte a [email protected] o utilice el chat en vivo del dashboard.
5

Entorno Mainnet

La disponibilidad depende de las rutas de proveedor configuradas. Las solicitudes de testnet usan solo rutas y wallets de testnet; las solicitudes de mainnet usan solo rutas y wallets de mainnet.
6

Soporte de stablecoin

Depositar fiat y convertirlo en una stablecoin es una función de pago. Asegúrese de que su plan incluya acceso a stablecoins. Actualice desde Dashboard → Settings → Subscription.

Cómo funciona

Descubrir opciones

Consulte los activos y las monedas disponibles para su wallet.

Obtener requisitos

Recupere el esquema que describe lo que necesita el corredor seleccionado.

Crear cuenta

Cree una cuenta virtual con additionalData y un label opcional.

Auto-Funding

El fiat entrante emite automáticamente la stablecoin equivalente en la wallet o dirección vinculada.

Monedas fiat compatibles

Las monedas varían según el corredor y el proveedor. Consulte siempre lo que está disponible para su wallet con el endpoint de descubrimiento en lugar de codificar la lista de forma fija. El snapshot de abajo muestra USD, EUR y los principales corredores de LATAM; vea la matriz completa en la página Monedas Fiat Compatibles.

Flujo de Auto-Funding

Todas las cuentas virtuales utilizan AUTO_FUNDING, que convierte automáticamente fiat en stablecoin. Cuando un cliente envía fiat a una cuenta virtual:

1. Recepción del pago

El pago se recibe en la cuenta virtual mediante una transferencia bancaria. En esta etapa se dispara un webhook onramp.processing.

2. Emisión automática

El sistema emite automáticamente el equivalente en stablecoin en la blockchain.

3. Transferencia en blockchain

La stablecoin emitida se transfiere a la wallet o dirección vinculada a la cuenta virtual. Al completarse con éxito se dispara un webhook onramp.success.

Activos y monedas compatibles

v2 admite múltiples stablecoins y monedas. En lugar de asumir un par fijo, consulte lo que está disponible para su wallet con el endpoint de descubrimiento. Por ejemplo, las transferencias bancarias en NGN pueden auto-fondear cNGN, mientras que otros corredores se liquidan en USDC u otros activos compatibles.

Endpoints de la API

Endpoints de Wallet Maestra

Endpoints de Dirección Secundaria

Paso 1: Descubrir opciones

Consulte los activos y las monedas disponibles para su wallet para cuentas virtuales.
Discovery Response

Paso 2: Obtener requisitos

Consulte el esquema que describe lo que requiere la moneda seleccionada (y opcionalmente el activo). Interprételo y complételo con Formularios dinámicos.
Requirements Response
Si additionalDataRequired es false, puede omitir la recopilación de additionalData y crear la cuenta directamente. Use el provider devuelto aquí al crear la cuenta.

Paso 3: Crear una cuenta virtual

Cree una cuenta virtual para una master wallet o child address. Envíe el objeto additionalData validado construido a partir del esquema de requisitos.

Ejemplo de respuesta

Cambiar el destino de una cuenta virtual

Los proveedores que admiten cambios de destino pueden apuntar una cuenta virtual existente a otra master wallet o child address sin reemplazar sus datos bancarios.Primero, descubra los destinos admitidos por el proveedor y la moneda fiat actuales de la cuenta virtual:
La respuesta agrupa los activos de liquidación admitidos por wallet. supported: false significa que el proveedor actual no admite cambiar destinos. Las opciones de destino siempre coinciden con el entorno de la solicitud: las solicitudes de testnet devuelven solo wallets y rutas de testnet, mientras que las solicitudes de mainnet devuelven solo wallets y rutas de mainnet.
Destination Discovery Response
Después de elegir una wallet y un activo, opcionalmente obtenga las child addresses de la wallet con los endpoints de direcciones existentes. Omita addressId para usar la dirección de la master wallet.
La API vuelve a validar el destino contra las rutas de conversión activas del proveedor antes de aplicar el cambio. Devuelve 409 Conflict cuando la cuenta virtual ya usa el destino seleccionado. Una discrepancia en la confirmación del proveedor devuelve 502 Bad Gateway, y el destino local permanece sin cambios.

Listado de cuentas virtuales

El endpoint de listado devuelve una lista paginada de cuentas virtuales. Utilice los parámetros de consulta para buscar, filtrar por estado de activación y filtrar por rango de fechas.

Parámetros de consulta

Response Example

Obtener una cuenta virtual específica

Para obtener una cuenta virtual específica por ID, utilice la API de Obtener Cuenta Virtual para wallets maestras o la API de Obtener Cuenta Virtual para direcciones secundarias.

Transacciones de cuenta virtual

Obtenga las transacciones asociadas a una cuenta virtual usando el endpoint de transacciones de dirección secundaria. Cada evento de auto-funding también se entrega mediante webhooks.

Parámetros de consulta

Response Example

Actualización de cuentas virtuales

Active o desactive una cuenta virtual para controlar el comportamiento de auto-funding. Utilice la API de Actualizar Cuenta Virtual para wallets maestras o la API de Actualizar Cuenta Virtual para direcciones secundarias.

Comportamiento de Auto-Funding

  • Cuentas activas: Los pagos recibidos disparan la emisión automática de stablecoin.
  • Cuentas inactivas: Los pagos se reciben pero el auto-funding está deshabilitado.

Parámetros de actualización

Request Example
Cuando se desactiva una cuenta virtual (isActive: false), aún se pueden recibir pagos pero el proceso automático de emisión y transferencia de stablecoin queda deshabilitado. Puede reactivar la cuenta en cualquier momento para volver a habilitar el auto-funding.

Regeneración de cuentas virtuales

El endpoint de regeneración crea una nueva cuenta virtual para un cliente mientras desactiva la existente. Esto es útil cuando:
  • Los datos bancarios de un cliente deben cambiar
  • La cuenta virtual ha sido comprometida
  • Necesita migrar a un cliente a un proveedor diferente

Parámetros de regeneración

Request Example
La operación de regeneración desactiva la cuenta virtual existente y crea una nueva. El historial de transacciones de la cuenta original se conserva y aún se puede consultar.

Webhooks

Las cuentas virtuales disparan eventos de webhook cuando se reciben y procesan los pagos. La liquidación de fiat a cripto usa la familia unificada de eventos de transacción onramp.*.

Eventos de Webhook

  1. onramp.processing — Se dispara cuando se detecta el pago en fiat y comienza la liquidación.
  2. onramp.success — Se dispara cuando el activo de destino se liquida en la wallet o dirección vinculada.
  3. onramp.failed — Se dispara si el onramp no puede completarse.
  4. onramp.cancelled — Se dispara si el onramp se cancela antes de completarse.

Ejemplo de payload de Webhook

Los webhooks solo se disparan para cuentas virtuales activas (isActive: true). Si una cuenta está desactivada, los pagos aún pueden recibirse pero los eventos de webhook no se enviarán hasta que la cuenta sea reactivada.
Para el payload canónico, las reglas de relación con el origen y el manejo de eventos, consulte Webhooks de transacciones de onramp.

Próximos pasos

Una vez que la stablecoin esté en su wallet:
  • Swap — Convierta a USDT, USDC u otras stablecoins bajo demanda
  • Auto-Settlement — Convierta automáticamente a USDT/USDC en cada depósito

Casos de uso

Pagos de E-commerce

Cree cuentas virtuales para que los clientes reciban pagos por productos o servicios, convertidos automáticamente en stablecoins para su sistema de pagos basado en blockchain.

Servicios de suscripción

Vincule cuentas virtuales a las suscripciones de los clientes, permitiendo transferencias bancarias recurrentes que se convierten automáticamente en stablecoins.

Transacciones de marketplace

Habilite transacciones donde los clientes envían pagos en fiat que se convierten al instante en stablecoins y se acreditan en su wallet.

Servicios de remesas

Proporcione a los clientes cuentas virtuales para recibir remesas en moneda local, convertidas automáticamente en stablecoins para transferencias transfronterizas.

Buenas prácticas

Gestión de cuentas

  • Use el esquema de requisitos: Recopile solo los campos del esquema de requisitos actual. No codifique de forma fija los campos de incorporación — consulte Formularios dinámicos.
  • Reutilice el proveedor devuelto: Cree con el provider devuelto por la solicitud de requisitos.
  • Etiquete sus cuentas: Establezca un label para que las cuentas sean buscables y fáciles de conciliar.
  • Activación de cuentas: Desactive las cuentas que no esté listo para fondear; reactívelas cuando esté listo.
  • Documente los motivos de regeneración: Proporcione siempre un reason claro al regenerar para fines de auditoría.

Seguridad

  • Verificación del cliente: Verifique la información del cliente antes de crear cuentas virtuales.
  • Preserve las cadenas: Envíe los identificadores y códigos como cadenas para evitar la pérdida de precisión.
  • Control de acceso: Implemente controles de acceso adecuados para la gestión de cuentas virtuales.

Manejo de errores

La API devuelve códigos de estado HTTP estándar y respuestas de error.

Ejemplo de respuesta de error

Referencia de API

v2 (recomendado)

Soporte

¿Necesita soporte para stablecoins o monedas adicionales? Contacte a [email protected].