Cuentas Virtuales - Blockradar

La API de Cuentas Virtuales proporciona endpoints para gestionar cuentas bancarias virtuales vinculadas a billeteras principales o direcciones secundarias. Esta API permite a las empresas crear cuentas virtuales para que los clientes reciban pagos, recuperar detalles de cuentas virtuales y activar/desactivar cuentas virtuales.

Introducción

Las Cuentas Virtuales permiten a tus clientes recibir pagos en fiat a través de transferencias bancarias tradicionales, que se convierten automáticamente en stablecoins en la blockchain. Esto cierra la brecha entre la banca tradicional y los pagos con stablecoins, permitiendo un procesamiento de pagos sin problemas para tu negocio. Cuando un cliente envía moneda fiat a una cuenta virtual, el sistema puede acuñar automáticamente el equivalente en stablecoin y transferirlo a la billetera o dirección vinculada, proporcionando capacidades de procesamiento de pagos en tiempo real.

Cómo Funcionan las Cuentas Virtuales

Creación de Cuenta

Crea cuentas virtuales vinculadas a billeteras principales o direcciones secundarias con información del cliente.

Recepción de Pagos

Los clientes envían pagos en fiat a la cuenta virtual usando transferencias bancarias tradicionales.

Financiamiento Automático

Para cuentas de tipo AUTO_FUNDING, los pagos activan automáticamente la acuñación de la stablecoin.

Gestión de Fondos

Las stablecoins acuñadas se transfieren a la billetera o dirección vinculada para uso inmediato.

Tipos de Cuentas Virtuales

Las cuentas virtuales admiten diferentes tipos con comportamientos variables:

AUTO_FUNDING (Predeterminado)

Acuña automáticamente stablecoin cuando se reciben pagos en fiat
Transfiere stablecoin a la billetera/dirección vinculada inmediatamente
Mejor para procesamiento de pagos en tiempo real
Proporciona conversión instantánea de fiat a stablecoin

El flujo de financiamiento automático solo se aplica a cuentas virtuales con tipo AUTO_FUNDING. Otros tipos tienen diferentes comportamientos de procesamiento.

Cómo Funciona - Flujo de Financiamiento Automático

Cuando un cliente envía moneda fiat a una cuenta virtual con tipo AUTO_FUNDING:

1. Recepción de Pago

El pago se recibe en la cuenta virtual a través de transferencia bancaria tradicional. Un webhook deposit.processing se activa en esta etapa.

2. Minting Automático

El sistema hace un minting automáticamente al equivalente en stablecoin en la blockchain.

3. Transferencia en Blockchain

La stablecoin acuñada se transfiere a la billetera o dirección vinculada de la cuenta virtual. Un webhook deposit.success se activa al completarse con éxito.

El flujo de financiamiento automático solo se aplica a cuentas virtuales con tipo AUTO_FUNDING. Otros tipos tienen diferentes comportamientos de procesamiento.

Requisitos Previos

Antes de crear cuentas virtuales, asegúrate de:

Los requisitos de cumplimiento deben completarse (consulta la sección Requisitos de Cumplimiento a continuación)
La función de cuentas virtuales debe estar habilitada para tu negocio (contacta a [email protected] o usa el chat en vivo en el panel de control para habilitar la función después de la aprobación de cumplimiento)
Solo disponible en entorno MAINNET (no disponible en testnet)
La billetera principal debe admitir activos de stablecoin - Tu plan de cuenta debe incluir acceso a stablecoin (actualiza desde Panel de Control → Configuración → Suscripción si es necesario)

Entorno: Las cuentas virtuales solo están disponibles en el entorno MAINNET. Los entornos de testnet no admiten la creación u operaciones de cuentas virtuales.

Requisitos de Cumplimiento

Antes de solicitar acceso a la función de cuentas virtuales, debes completar el proceso de incorporación de cumplimiento. Se requieren los siguientes documentos e información:

Documentos Requeridos

Certificado de Incorporación para tu negocio y una lista de accionistas (por ejemplo, documento MEMART del CAC de Nigeria)
Factura de servicios públicos reciente para confirmar la dirección del negocio
Tarjetas de identificación de UBO(s) (Propietarios Beneficiarios Últimos) y Directores
Certificado Fiscal/TIN
Política KYC de la Compañía
Política AML/CFT/CPF de la Compañía
Facturas de servicios públicos recientes de UBO(s) y Directores

Envío de Documentos de Cumplimiento

Envía todos los documentos e información requeridos por correo electrónico al equipo de cumplimiento:

Email: [email protected]
CC: [email protected], [email protected]

El proceso de revisión de cumplimiento debe completarse antes de que las cuentas virtuales puedan habilitarse para tu negocio. Asegúrate de que todos los documentos estén actualizados y formateados correctamente antes del envío.

Moneda Admitida

Fiat: NGN (Naira Nigeriana) - Transferencias bancarias tradicionales
Stablecoin: cNGN - Acuñada automáticamente en blockchain (para tipo AUTO_FUNDING)

Endpoints de la API

A continuación se muestran los endpoints principales de la API para operaciones de Cuentas Virtuales:

Endpoints de Billetera Principal

POST /wallets//virtual-accounts – Crear una cuenta virtual para una billetera principal
GET /wallets//virtual-accounts – Recuperar detalles de cuenta virtual
PATCH /wallets//virtual-accounts/ – Actualizar estado de cuenta virtual

Endpoints de Dirección Secundaria

POST /wallets//addresses//virtual-accounts – Crear una cuenta virtual para una dirección secundaria
GET /wallets//addresses//virtual-accounts – Recuperar detalles de cuenta virtual
PATCH /wallets//addresses//virtual-accounts/ – Actualizar estado de cuenta virtual

Creación de Cuentas Virtuales

Puedes crear cuentas virtuales tanto para billeteras principales como para direcciones secundarias, dependiendo de tu caso de uso. Usa la API de Crear Cuenta Virtual para billeteras principales o la API de Crear Cuenta Virtual para direcciones secundarias.

Parámetros de Solicitud

Parámetro	Tipo	Requerido	Descripción
`firstname`	string	Sí	Nombre del cliente
`lastname`	string	Sí	Apellido del cliente
`email`	string	Sí	Dirección de correo electrónico del cliente (debe ser única por negocio)
`phone`	string	Sí	Número de teléfono del cliente en formato: +234XXXXXXXXXX

Ejemplo de Respuesta

{
  "data": {
    "id": "8180309e-1ead-4a72-a013-b5674600ce4c",
    "accountName": "John Doe",
    "accountNumber": "9018927611",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "type": "AUTO_FUNDING",
    "isActive": true,
    "status": "ACTIVE",
    "reference": "20",
    "customer": {
      "id": "caa17eb8-4da8-45b4-a866-81dd0a1df613",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "createdAt": "2025-11-06T18:30:34.286Z",
    "updatedAt": "2025-11-06T18:30:34.286Z"
  },
  "message": "Virtual account created successfully",
  "statusCode": 201
}

Recuperación de Cuentas Virtuales

Para recuperar detalles de cuentas virtuales, usa la API de Obtener Cuenta Virtual para billeteras principales o la API de Obtener Cuenta Virtual para direcciones secundarias.

Actualización de Cuentas Virtuales

Puedes activar o desactivar cuentas virtuales para controlar el comportamiento del financiamiento automático. Usa la API de Actualizar Cuenta Virtual para billeteras principales o la API de Actualizar Cuenta Virtual para direcciones secundarias.

Comportamiento del Financiamiento Automático

Cuentas activas: Los pagos recibidos activan la acuñación automática de stablecoin
Cuentas inactivas: Los pagos se reciben pero el financiamiento automático está deshabilitado

Parámetros de Actualización

Parámetro	Tipo	Requerido	Descripción
`isActive`	boolean	Sí	`true` para activar, `false` para desactivar

Cuando una cuenta virtual se desactiva (isActive: false), los pagos aún pueden recibirse pero el proceso automático de acuñación y transferencia de stablecoin está deshabilitado. Puedes reactivar la cuenta en cualquier momento para volver a habilitar el financiamiento automático.

Webhooks

Las cuentas virtuales activan eventos de webhook cuando se reciben y procesan pagos. Para cuentas de tipo AUTO_FUNDING, recibirás notificaciones de webhook en cada etapa del flujo de procesamiento de pagos.

Eventos de Webhook

Cuando un cliente envía un pago en fiat a una cuenta virtual con tipo AUTO_FUNDING:

deposit.processing - Se activa inmediatamente cuando se recibe el pago en fiat en la cuenta virtual. Esto indica que el pago ha sido detectado y el proceso de acuñación está por comenzar.
deposit.success - Se activa cuando la stablecoin ha sido acuñada con éxito y transferida a la billetera o dirección vinculada. Esto confirma que todo el proceso de financiamiento automático está completo.
deposit.failed - Se activa si el proceso de acuñación o transferencia falla en cualquier punto.
deposit.cancelled - Se activa si la transacción se cancela antes de completarse.

Carga de Webhook

La carga del webhook sigue el formato estándar de webhook de depósito. El type de transacción será DEPOSIT, y el campo status reflejará el estado actual (PROCESSING, SUCCESS, FAILED o CANCELLED).

Los webhooks solo se activan 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 se reactive.

Para más información sobre la configuración de webhooks, estructura de carga y manejo de eventos, consulta la documentación de Webhooks.

Casos de Uso

Pagos de Comercio Electrónico

Crea cuentas virtuales para que los clientes reciban pagos por productos o servicios. La conversión automática a stablecoins permite una integración sin problemas con tu sistema de pagos basado en blockchain.

Servicios de Suscripción

Vincula cuentas virtuales a suscripciones de clientes, permitiendo pagos recurrentes a través de transferencias bancarias tradicionales que se convierten automáticamente en stablecoins.

Transacciones de Mercado

Habilita transacciones peer-to-peer donde los clientes pueden enviar pagos en fiat que se convierten instantáneamente en stablecoins y se acreditan en su billetera.

Servicios de Remesas

Proporciona a los clientes cuentas virtuales para recibir remesas en NGN, que se convierten automáticamente en stablecoins para transferencias transfronterizas fáciles.

Mejores Prácticas

Gestión de Cuentas

Direcciones de correo electrónico únicas: Asegúrate de que cada cliente tenga una dirección de correo electrónico única
Formato de número de teléfono: Usa siempre el formato correcto (+234XXXXXXXXXX) para números de teléfono nigerianos
Activación de cuenta: Activa cuentas solo cuando estés listo para procesar pagos
Monitorear estado de cuenta: Verifica regularmente el estado de la cuenta y maneja las cuentas inactivas apropiadamente

Seguridad

Verificación de clientes: Verifica la información del cliente antes de crear cuentas virtuales
Validación de cuentas: Valida los detalles de la cuenta antes de procesar pagos
Control de acceso: Implementa controles de acceso adecuados para la gestión de cuentas virtuales

Soporte y Recursos

Obtener Ayuda

Soporte para más stablecoins y monedas: Contacta a [email protected] para habilitar soporte para tu stablecoin y moneda
Email: [email protected]
Chat en vivo: Disponible en el panel de control
Referencia de API: Cuentas Virtuales

Las cuentas virtuales proporcionan una forma poderosa de conectar la banca tradicional con pagos blockchain. Comienza creando cuentas para tus billeteras principales, luego expande a direcciones secundarias según tu caso de uso lo requiera. Asegúrate siempre de que tus billeteras admitan stablecoin para cuentas de tipo AUTO_FUNDING.

¡Feliz programación! ❤️

Comenzar

Esenciales

​Introducción

​Cómo Funcionan las Cuentas Virtuales

Creación de Cuenta

Recepción de Pagos

Financiamiento Automático

Gestión de Fondos

​Tipos de Cuentas Virtuales

​AUTO_FUNDING (Predeterminado)

​Cómo Funciona - Flujo de Financiamiento Automático

​1. Recepción de Pago

​2. Minting Automático

​3. Transferencia en Blockchain

​Requisitos Previos

​Requisitos de Cumplimiento

​Documentos Requeridos

​Envío de Documentos de Cumplimiento

​Moneda Admitida

​Endpoints de la API

​Endpoints de Billetera Principal

​Endpoints de Dirección Secundaria

​Creación de Cuentas Virtuales

​Parámetros de Solicitud

​Ejemplo de Respuesta

​Recuperación de Cuentas Virtuales

​Actualización de Cuentas Virtuales

​Comportamiento del Financiamiento Automático

​Parámetros de Actualización

​Webhooks

​Eventos de Webhook

​Carga de Webhook

​Casos de Uso

​Pagos de Comercio Electrónico

​Servicios de Suscripción

​Transacciones de Mercado

​Servicios de Remesas

​Mejores Prácticas

​Gestión de Cuentas

​Seguridad

​Soporte y Recursos

​Obtener Ayuda

Introducción

Cómo Funcionan las Cuentas Virtuales

Tipos de Cuentas Virtuales

AUTO_FUNDING (Predeterminado)

Cómo Funciona - Flujo de Financiamiento Automático

1. Recepción de Pago

2. Minting Automático

3. Transferencia en Blockchain

Requisitos Previos

Requisitos de Cumplimiento

Documentos Requeridos

Envío de Documentos de Cumplimiento

Moneda Admitida

Endpoints de la API

Endpoints de Billetera Principal

Endpoints de Dirección Secundaria

Creación de Cuentas Virtuales

Parámetros de Solicitud

Ejemplo de Respuesta

Recuperación de Cuentas Virtuales

Actualización de Cuentas Virtuales

Comportamiento del Financiamiento Automático

Parámetros de Actualización

Webhooks

Eventos de Webhook

Carga de Webhook

Casos de Uso

Pagos de Comercio Electrónico

Servicios de Suscripción

Transacciones de Mercado

Servicios de Remesas

Mejores Prácticas

Gestión de Cuentas

Seguridad

Soporte y Recursos

Obtener Ayuda