> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Cuentas Virtuales
> Crea y gestiona cuentas bancarias virtuales vinculadas a billeteras principales o direcciones secundarias para pagos de fiat a stablecoin sin problemas
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:
Obtén tu clave API desde el [Panel de Blockradar](https://dashboard.blockradar.co). Navega a **Developers** para generar una.
Crea una billetera a través de la [API de Crear Billetera](/es/api-reference/wallets/create-wallet) o el panel. Necesitarás el `walletId` para operaciones de cuentas virtuales.
Completa el [Formulario de Due Diligence](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) (consulta [Requisitos de Cumplimiento](#requisitos-de-cumplimiento) abajo).
Solicita la activación de la función de cuentas virtuales después de la aprobación de cumplimiento. Contacta a [support@blockradar.co](mailto:support@blockradar.co) o usa el chat en vivo en el panel.
Las cuentas virtuales solo están disponibles en **MAINNET**. Los entornos de testnet no admiten operaciones de cuentas virtuales.
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
Crea cuentas virtuales vinculadas a billeteras principales o direcciones secundarias con
información del cliente.
Los clientes envían pagos en fiat a la cuenta virtual usando transferencias bancarias
tradicionales.
Los pagos activan automáticamente la acuñación del equivalente en stablecoin.
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](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) 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/{walletId}/virtual-accounts](/es/api-reference/virtual-accounts/master-wallet-create) – Crear una cuenta virtual para una billetera principal
* [GET /wallets/{walletId}/virtual-accounts](/es/api-reference/virtual-accounts/master-wallet-get-all) – Listar todas las cuentas virtuales (paginado)
* [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/es/api-reference/virtual-accounts/master-wallet-get-one) – Recuperar una cuenta virtual específica
* [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/es/api-reference/virtual-accounts/master-wallet-transactions) – Obtener transacciones de una cuenta virtual
* [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/es/api-reference/virtual-accounts/master-wallet-update) – Actualizar estado de cuenta virtual
* [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/es/api-reference/virtual-accounts/master-wallet-regenerate) – Regenerar una cuenta virtual
### **Endpoints de Dirección Secundaria**
* [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/es/api-reference/virtual-accounts/child-address-create) – Crear una cuenta virtual para una dirección secundaria
* [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/es/api-reference/virtual-accounts/child-address-get-all) – Listar todas las cuentas virtuales (paginado)
* [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/es/api-reference/virtual-accounts/child-address-get-one) – Recuperar una cuenta virtual específica
* [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/es/api-reference/virtual-accounts/child-address-transactions) – Obtener transacciones de una cuenta virtual
* [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/es/api-reference/virtual-accounts/child-address-update) – Actualizar estado de cuenta virtual
* [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/es/api-reference/virtual-accounts/child-address-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](/es/api-reference/virtual-accounts/master-wallet-create) para billeteras principales o la [API de Crear Cuenta Virtual para direcciones secundarias](/es/api-reference/virtual-accounts/child-address-create).
### **Parámetros de Solicitud para Billetera Principal**
| 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 |
| `bvn` | string | Sí | Bank Verification Number del cliente |
| `dateOfBirth` | string | Sí | Fecha de nacimiento del cliente en formato `yyyy-MM-dd` |
### **Ejemplo de Solicitud para Billetera Principal**
```json theme={null}
{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"phone": "+2348161846125",
"bvn": "22345678901",
"dateOfBirth": "1992-08-14"
}
```
### **Parámetros de Solicitud para Dirección Secundaria**
| 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 |
| `bvn` | string | Sí | Bank Verification Number del cliente |
| `dateOfBirth` | string | Sí | Fecha de nacimiento del cliente en formato `yyyy-MM-dd` |
### **Ejemplo de Solicitud para Dirección Secundaria**
```json theme={null}
{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"phone": "+2348161846125",
"bvn": "22345678901",
"dateOfBirth": "1992-08-14"
}
```
### **Ejemplo de Respuesta**
```json theme={null}
{
"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": "john.doe@example.com",
"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**
```json theme={null}
{
"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": "john.doe@example.com",
"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](/es/api-reference/virtual-accounts/master-wallet-get-one) o la [API de Obtener Cuenta Virtual para direcciones secundarias](/es/api-reference/virtual-accounts/child-address-get-one).
### **Ejemplo de Respuesta**
```json theme={null}
{
"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": "john.doe@example.com",
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"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](/es/api-reference/virtual-accounts/master-wallet-update) o la [API de Actualizar Cuenta Virtual para direcciones secundarias](/es/api-reference/virtual-accounts/child-address-update).
### **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**
```json theme={null}
{
"isActive": false
}
```
### **Ejemplo de Respuesta**
```json theme={null}
{
"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:
1. **`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.
2. **`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.
3. **`deposit.failed`** - Se activa si el proceso de acuñación o transferencia falla en cualquier punto.
4. **`deposit.cancelled`** - Se activa si la transacción se cancela antes de completarse.
### **Ejemplo de Payload de Webhook**
```json theme={null}
{
"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](/es/essentials/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](/es/essentials/swap)** - Convierte cNGN a USDT, USDC u otras stablecoins bajo demanda
* **[Auto-Settlement](/es/essentials/auto-settlements)** - 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**
```json theme={null}
{
"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**: [support@blockradar.co](mailto:support@blockradar.co)
* **Chat en vivo**: Disponible en el panel de control
* **Referencia de API**: [API de Cuentas Virtuales](/es/api-reference/virtual-accounts/master-wallet-get-all)
¿Necesitas soporte para stablecoins o monedas adicionales? Contacta a [support@blockradar.co](mailto:support@blockradar.co).