Cuentas Virtuales - Blockradar

En pocas palabras
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. Puedes crear múltiples cuentas virtuales por billetera o dirección, con soporte para etiquetado, paginación y regeneración de cuentas.

Requisitos Previos

Antes de usar la API de Cuentas Virtuales, asegúrate de tener:

Clave API

Obtén tu clave API desde el Panel de Blockradar. Navega a Developers para generar una.

Billetera Creada

Crea una billetera a través de la API de Crear Billetera o el panel. Necesitarás el walletId para operaciones de cuentas virtuales.

Cumplimiento Aprobado

Completa el Formulario de Due Diligence (consulta Requisitos de Cumplimiento abajo).

Función Habilitada

Solicita la activación de la función de cuentas virtuales después de la aprobación de cumplimiento. Contacta a [email protected] o usa el chat en vivo en el panel.

Entorno Mainnet

Las cuentas virtuales solo están disponibles en MAINNET. Los entornos de testnet no admiten operaciones de cuentas virtuales.

Soporte de Stablecoin

Asegúrate de que tu plan de cuenta incluya acceso a stablecoin. Actualiza desde Panel → Configuración → Suscripción si es necesario.

Cómo Funciona

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

Los pagos activan automáticamente la acuñación del equivalente en stablecoin.

Gestión de Fondos

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

Flujo de Financiamiento Automático

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

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. Acuñación Automática

El sistema acuña automáticamente el 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.

Requisitos de Cumplimiento

Antes de acceder a las cuentas virtuales, completa el proceso de incorporación de cumplimiento.

Documentos Requeridos

Certificado de Incorporación
ID para Directores/Accionistas
Documento de Política KYC

Enviar Solicitud

Completa el Formulario de Due Diligence con los detalles de tu empresa, información de cumplimiento y carga de documentos.

Moneda Admitida

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

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 – Listar todas las cuentas virtuales (paginado)
GET /wallets//virtual-accounts/ – Recuperar una cuenta virtual específica
GET /wallets//virtual-accounts//transactions – Obtener transacciones de una cuenta virtual
PATCH /wallets//virtual-accounts/ – Actualizar estado de cuenta virtual
POST /wallets//virtual-accounts//regenerate – Regenerar una 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 – Listar todas las cuentas virtuales (paginado)
GET /wallets//addresses//virtual-accounts/ – Recuperar una cuenta virtual específica
GET /wallets//addresses//virtual-accounts//transactions – Obtener transacciones de una cuenta virtual
PATCH /wallets//addresses//virtual-accounts/ – Actualizar estado de cuenta virtual
POST /wallets//addresses//virtual-accounts//regenerate – Regenerar una 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 (máx. 29 caracteres)
`lastname`	string	Sí	Apellido del cliente (máx. 29 caracteres)
`email`	string	Sí	Dirección de correo electrónico del cliente (debe ser única por negocio)
`phone`	string	No	Número de teléfono del cliente en formato: +234XXXXXXXXXX
`label`	string	No	Etiqueta personalizada para identificar esta cuenta virtual (máx. 100 caracteres)

Ejemplo de Solicitud

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "label": "Cuenta Principal"
}

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",
    "label": "Cuenta Principal",
    "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
}

Múltiples Cuentas Virtuales

Puedes crear múltiples cuentas virtuales por billetera o dirección secundaria. Esto es útil cuando:

Un cliente necesita cuentas separadas para diferentes propósitos (ej., ahorros, pagos)
Quieres rastrear pagos de diferentes fuentes por separado
La cuenta virtual existente de un cliente necesita ser reemplazada manteniendo el historial

Solo una cuenta virtual por correo electrónico de cliente puede estar activa a la vez. Crear una nueva cuenta virtual para el mismo correo electrónico requerirá desactivar la existente primero, o usar el endpoint de regeneración.

Listado de Cuentas Virtuales

El endpoint de listado devuelve una lista paginada de todas las cuentas virtuales. Usa parámetros de consulta para filtrar y paginar resultados.

Parámetros de Consulta

Parámetro	Tipo	Descripción
`page`	number	Número de página (predeterminado: 1)
`limit`	number	Resultados por página (predeterminado: 10)
`isActive`	boolean	Filtrar por estado activo (`true` o `false`)

Ejemplo de Respuesta

{
  "message": "Virtual accounts retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "reference": "172",
      "accountNumber": "9012271961",
      "accountName": "John Doe",
      "bankName": "Polaris Bank",
      "bankCode": "076",
      "currency": "NGN",
      "isActive": true,
      "status": "ACTIVE",
      "type": "AUTO_FUNDING",
      "label": null,
      "createdAt": "2025-01-21T22:15:55.746Z",
      "updatedAt": "2025-01-21T22:15:55.746Z",
      "customer": {
        "id": "3082e278-557a-44f0-9205-c2639560cd5a",
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+2346112768485",
        "status": "ACTIVE",
        "network": "mainnet"
      },
      "wallet": {
        "id": "35e964a6-436a-424f-bf3a-618cc060feea",
        "name": "Base Wallet",
        "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
      },
      "address": null
    }
  ],
  "meta": {
    "totalItems": 4,
    "itemCount": 4,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

Recuperación de una Cuenta Virtual

Para recuperar una cuenta virtual específica por ID, usa la API de Obtener Cuenta Virtual para billeteras principales o la API de Obtener Cuenta Virtual para direcciones secundarias.

Ejemplo de Respuesta

{
  "message": "Virtual account retrieved successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "reference": "172",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "isActive": true,
    "status": "ACTIVE",
    "type": "AUTO_FUNDING",
    "label": "Cuenta Principal",
    "createdAt": "2025-01-21T22:15:55.746Z",
    "updatedAt": "2025-01-21T22:15:55.746Z",
    "customer": {
      "id": "3082e278-557a-44f0-9205-c2639560cd5a",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "address": null
  }
}

Transacciones de Cuenta Virtual

Puedes recuperar todas las transacciones asociadas con una cuenta virtual específica usando el endpoint de transacciones.

Parámetros de Consulta

Parámetro	Tipo	Descripción
`page`	number	Número de página (predeterminado: 1)
`limit`	number	Resultados por página (predeterminado: 10)

Ejemplo de Respuesta

{
  "message": "Virtual account transactions retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "0.03382",
      "currency": "NGN",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN to 0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "network": "mainnet",
      "metadata": {
        "autoFunding": {
          "narration": "NIBSS:9018927611:SULEIMAN, ABDULFATAI:Sending:090267251107014024497001670835",
          "sessionId": "09026725110701402449700167083590131815",
          "senderBankName": "KUDA MFB",
          "senderAccountName": "SULEIMAN, ABDULFATAI"
        }
      },
      "createdAt": "2025-01-22T22:29:28.679Z",
      "asset": {
        "name": "cNGN",
        "symbol": "cNGN",
        "currency": "NGN"
      },
      "blockchain": {
        "name": "base",
        "slug": "base"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "itemCount": 1,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

El campo metadata.autoFunding contiene detalles sobre la fuente del pago en fiat, incluyendo el nombre del banco del remitente, nombre de la cuenta y la narración de la transferencia bancaria.

Regeneración de Cuentas Virtuales

El endpoint de regeneración te permite crear una nueva cuenta virtual para un cliente mientras desactivas la existente. Esto es útil cuando:

Los detalles bancarios de un cliente necesitan cambiar
La cuenta virtual ha sido comprometida
Necesitas migrar a un cliente a un banco diferente

Parámetros de Regeneración

Parámetro	Tipo	Requerido	Descripción
`firstname`	string	Sí	Nombre del cliente (máx. 29 caracteres)
`lastname`	string	Sí	Apellido del cliente (máx. 29 caracteres)
`email`	string	Sí	Dirección de correo electrónico del cliente
`phone`	string	No	Número de teléfono del cliente en formato: +234XXXXXXXXXX
`reason`	string	Sí	Razón para regenerar la cuenta virtual
`label`	string	No	Etiqueta personalizada para la nueva cuenta virtual

Ejemplo de Solicitud

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "Cliente solicitó nuevo número de cuenta",
  "label": "Nueva Cuenta Principal"
}

La operación de regeneración desactivará la cuenta virtual existente y creará una nueva. El historial de transacciones de la cuenta original se preserva y aún puede consultarse.

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

Ejemplo de Solicitud

{
  "isActive": false
}

Ejemplo de Respuesta

{
  "message": "Virtual account updated successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "isActive": false,
    "status": "INACTIVE",
    "type": "AUTO_FUNDING",
    "label": "Cuenta Principal"
  }
}

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

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.

Ejemplo de Payload de Webhook

{
  "event": "deposit.success",
  "data": {
    "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
    "reference": "auto-funding-09026725110701402449700167083590131815",
    "amount": "50.0",
    "currency": "NGN",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "network": "mainnet",
    "metadata": {
      "autoFunding": {
        "sessionId": "09026725110701402449700167083590131815",
        "senderBankName": "KUDA MFB",
        "senderAccountName": "SULEIMAN, ABDULFATAI"
      }
    },
    "virtualAccount": {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "accountNumber": "9012271961",
      "bankName": "Polaris Bank"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet"
    }
  }
}

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

Próximos Pasos

Una vez que cNGN esté en tu billetera:

Swap - Convierte cNGN a USDT, USDC u otras stablecoins bajo demanda
Auto-Settlement - Convierte automáticamente cNGN a USDT/USDC en cada depósito

Mejores Prácticas

Gestión de Cuentas

Usa etiquetas descriptivas: Agrega etiquetas significativas a las cuentas virtuales (ej., “Ahorros”, “Pagos”) para fácil identificación
Direcciones de correo electrónico únicas: Asegúrate de que cada cliente tenga una dirección de correo electrónico única por cuenta activa
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
Documentar razones de regeneración: Proporciona siempre razones claras al regenerar cuentas para fines de auditoría

Múltiples Cuentas

Planifica tu estructura de cuentas: Decide por adelantado cuántas cuentas puede necesitar cada cliente
Usa etiquetas consistentemente: Establece una convención de nomenclatura para etiquetas en tu aplicación
Rastrea el historial de cuentas: Al regenerar, mantén referencias a IDs de cuentas anteriores para reconciliación de transacciones

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

Manejo de Errores

La API devuelve códigos de estado HTTP estándar y respuestas de error. Los errores comunes incluyen:

Código de Estado	Error	Descripción
`400`	Bad Request	Parámetros de solicitud inválidos (ej., formato de email inválido, nombre excede 29 caracteres)
`401`	Unauthorized	Clave API faltante o inválida
`404`	Not Found	Cuenta virtual o billetera no encontrada
`409`	Conflict	El email ya existe para una cuenta virtual activa
`422`	Unprocessable Entity	Validación fallida (ej., campos requeridos faltantes)

Ejemplo de Respuesta de Error

{
  "message": "A virtual account with this email already exists",
  "statusCode": 409,
  "error": "Conflict"
}

Cuando recibas un error 409 por email duplicado, desactiva primero la cuenta virtual existente o usa el endpoint de regeneración para crear una nueva cuenta para el mismo cliente.

Soporte

Email: [email protected]
Chat en vivo: Disponible en el panel de control
Referencia de API: API de Cuentas Virtuales

¿Necesitas soporte para stablecoins o monedas adicionales? Contacta a [email protected].

Comenzar

Esenciales

​Requisitos Previos

​Cómo Funciona

Creación de Cuenta

Recepción de Pagos

Financiamiento Automático

Gestión de Fondos

​Flujo de Financiamiento Automático

​1. Recepción de Pago

​2. Acuñación Automática

​3. Transferencia en Blockchain

​Requisitos de Cumplimiento

​Documentos Requeridos

​Enviar Solicitud

​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 Solicitud

​Ejemplo de Respuesta

​Múltiples Cuentas Virtuales

​Listado de Cuentas Virtuales

​Parámetros de Consulta

​Ejemplo de Respuesta

​Recuperación de una Cuenta Virtual

​Ejemplo de Respuesta

​Transacciones de Cuenta Virtual

​Parámetros de Consulta

​Ejemplo de Respuesta

​Regeneración de Cuentas Virtuales

​Parámetros de Regeneración

​Ejemplo de Solicitud

​Actualización de Cuentas Virtuales

​Comportamiento del Financiamiento Automático

​Parámetros de Actualización

​Ejemplo de Solicitud

​Ejemplo de Respuesta

​Webhooks

​Eventos de Webhook

​Ejemplo de Payload de Webhook

​Casos de Uso

​Pagos de Comercio Electrónico

​Servicios de Suscripción

​Transacciones de Mercado

​Servicios de Remesas

​Próximos Pasos

​Mejores Prácticas

​Gestión de Cuentas

​Múltiples Cuentas

​Seguridad

​Manejo de Errores

​Ejemplo de Respuesta de Error

​Soporte

Requisitos Previos

Cómo Funciona

Flujo de Financiamiento Automático

1. Recepción de Pago

2. Acuñación Automática

3. Transferencia en Blockchain

Requisitos de Cumplimiento

Documentos Requeridos

Enviar Solicitud

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 Solicitud

Ejemplo de Respuesta

Múltiples Cuentas Virtuales

Listado de Cuentas Virtuales

Parámetros de Consulta

Ejemplo de Respuesta

Recuperación de una Cuenta Virtual

Ejemplo de Respuesta

Transacciones de Cuenta Virtual

Parámetros de Consulta

Ejemplo de Respuesta

Regeneración de Cuentas Virtuales

Parámetros de Regeneración

Ejemplo de Solicitud

Actualización de Cuentas Virtuales

Comportamiento del Financiamiento Automático

Parámetros de Actualización

Ejemplo de Solicitud

Ejemplo de Respuesta

Webhooks

Eventos de Webhook

Ejemplo de Payload de Webhook

Casos de Uso

Pagos de Comercio Electrónico

Servicios de Suscripción

Transacciones de Mercado

Servicios de Remesas

Próximos Pasos

Mejores Prácticas

Gestión de Cuentas

Múltiples Cuentas

Seguridad

Manejo de Errores

Ejemplo de Respuesta de Error

Soporte