> ## 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. # Depositar Fiat > Cree y gestione cuentas bancarias virtuales vinculadas a wallets maestras o direcciones secundarias para pagos fluidos de fiat a stablecoin En resumen
Las Cuentas Virtuales permiten que sus clientes reciban pagos en fiat mediante transferencias bancarias tradicionales, que se convierten automáticamente en stablecoins en la blockchain. Puede crear varias cuentas virtuales por wallet o dirección, con soporte para paginación y regeneración de cuentas. Cuentas Virtuales ## Requisitos previos Antes de utilizar la API de Cuentas Virtuales, asegúrese de contar con: Obtenga su clave de API desde el [Dashboard de Blockradar](https://dashboard.blockradar.co). Diríjase a **Developers** para generar una. Cree una wallet mediante la [API de Crear Wallet](/en/api-reference/wallets/create-wallet) o desde el dashboard. Necesitará el `walletId` para las operaciones con cuentas virtuales. Complete el [Formulario de Diligencia Debida](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) (consulte los [Requisitos de Cumplimiento](#requisitos-de-cumplimiento) más abajo). Solicite la activación de la función de cuentas virtuales tras la aprobación de cumplimiento. Contacte a [support@blockradar.co](mailto:support@blockradar.co) o utilice el chat en vivo del dashboard. Las cuentas virtuales solo están disponibles en **MAINNET**. Los entornos de testnet no admiten operaciones con cuentas virtuales. Depositar fiat y convertirlo en una stablecoin es una función de pago. Asegúrese de que su plan de cuenta incluya acceso a stablecoins. Actualice desde **Dashboard → Configuración → Suscripción**. ## Cómo funciona Cree cuentas virtuales vinculadas a wallets maestras o direcciones secundarias con la información del cliente. Los clientes envían pagos en fiat a la cuenta virtual mediante transferencias bancarias tradicionales. Los pagos activan automáticamente la emisión del importe equivalente en stablecoin. Las stablecoins emitidas se transfieren a la wallet o dirección vinculada para su uso inmediato. ## Flujo de Auto-Funding Todas las cuentas virtuales utilizan `AUTO_FUNDING`, que convierte automáticamente fiat en stablecoin. Cuando un cliente envía moneda fiat a una cuenta virtual: ### **1. Recepción del pago** El pago se recibe en la cuenta virtual mediante transferencia bancaria tradicional. En esta etapa se dispara un webhook `deposit.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 `deposit.success`. ## Requisitos de cumplimiento Antes de acceder a las cuentas virtuales, complete el proceso de incorporación de cumplimiento. ### **Documentos requeridos** * Certificado de Constitución * Identificación de Directores/Accionistas * Documento de Política KYC ### **Enviar solicitud** Complete el [Formulario de Diligencia Debida](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form) con los datos de su empresa, información de cumplimiento y la carga de documentos. ## Moneda admitida * **Fiat**: NGN (Naira nigeriano) - Transferencias bancarias tradicionales * **Stablecoin**: cNGN - Emitida automáticamente en la blockchain ## Endpoints de la API A continuación se muestran los endpoints principales de la API para operaciones con Cuentas Virtuales: ### **Endpoints de Wallet Maestra** * [POST /wallets/{walletId}/virtual-accounts](/en/api-reference/virtual-accounts/master-wallet-create) – Crear una cuenta virtual para una wallet maestra * [GET /wallets/{walletId}/virtual-accounts](/en/api-reference/virtual-accounts/master-wallet-get-all) – Listar todas las cuentas virtuales (paginado) * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/master-wallet-get-one) – Obtener una cuenta virtual específica * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/en/api-reference/virtual-accounts/master-wallet-transactions) – Obtener transacciones de una cuenta virtual * [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/master-wallet-update) – Actualizar el estado de una cuenta virtual * [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/en/api-reference/virtual-accounts/master-wallet-regenerate) – Regenerar una cuenta virtual ### **Endpoints de Dirección Secundaria** * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/en/api-reference/virtual-accounts/child-address-create) – Crear una cuenta virtual para una dirección secundaria * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/en/api-reference/virtual-accounts/child-address-get-all) – Listar todas las cuentas virtuales (paginado) * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/child-address-get-one) – Obtener una cuenta virtual específica * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/en/api-reference/virtual-accounts/child-address-transactions) – Obtener transacciones de una cuenta virtual * [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/child-address-update) – Actualizar el estado de una cuenta virtual * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/en/api-reference/virtual-accounts/child-address-regenerate) – Regenerar una cuenta virtual ## Creación de Cuentas Virtuales Puede crear cuentas virtuales tanto para wallets maestras como para direcciones secundarias, según su caso de uso. Utilice la [API de Crear Cuenta Virtual](/en/api-reference/virtual-accounts/master-wallet-create) para wallets maestras o la [API de Crear Cuenta Virtual para direcciones secundarias](/en/api-reference/virtual-accounts/child-address-create). ### **Parámetros de solicitud para Wallet Maestra** | Parámetro | Tipo | Requerido | Descripción | | ------------- | ------ | --------- | ----------------------------------------------------------- | | `firstname` | string | Sí | Nombre del cliente (máximo 29 caracteres) | | `lastname` | string | Sí | Apellido del cliente (máximo 29 caracteres) | | `email` | string | Sí | Correo electrónico del cliente (debe ser único por negocio) | | `phone` | string | No | Número de teléfono del cliente con 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 Wallet Maestra** ```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áximo 29 caracteres) | | `lastname` | string | Sí | Apellido del cliente (máximo 29 caracteres) | | `email` | string | Sí | Correo electrónico del cliente (debe ser único por negocio) | | `phone` | string | No | Número de teléfono del cliente con 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 Puede crear varias cuentas virtuales por wallet o dirección secundaria. Esto es útil cuando: * Un cliente necesita cuentas separadas para distintos propósitos (por ejemplo, ahorros, pagos) * Desea rastrear pagos de distintas fuentes por separado * La cuenta virtual existente de un cliente debe reemplazarse manteniendo el historial ## Listado de Cuentas Virtuales El endpoint de listado devuelve una lista paginada de todas las cuentas virtuales. Utilice los parámetros de consulta para filtrar y paginar los 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", "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 } } ``` ## 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](/en/api-reference/virtual-accounts/master-wallet-get-one) o la [API de Obtener Cuenta Virtual para direcciones secundarias](/en/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", "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 Puede obtener todas las transacciones asociadas a una cuenta virtual específica utilizando 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 los detalles del origen del pago en fiat, incluyendo el nombre del banco emisor, el nombre de la cuenta y la narración de la transacción de la transferencia bancaria. ## Regeneración de Cuentas Virtuales El endpoint de regeneración le permite crear una nueva cuenta virtual para un cliente desactivando la existente. Esto es útil cuando: * Los datos bancarios del cliente deben cambiar * La cuenta virtual ha sido comprometida * Necesita 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áximo 29 caracteres) | | `lastname` | string | Sí | Apellido del cliente (máximo 29 caracteres) | | `email` | string | Sí | Correo electrónico del cliente | | `phone` | string | No | Número de teléfono del cliente con formato: +234XXXXXXXXXX | | `reason` | string | Sí | Motivo de la regeneración de la cuenta virtual | ### **Ejemplo de solicitud** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "reason": "Customer requested new account number" } ``` La operación de regeneración desactivará la cuenta virtual existente y creará una nueva. El historial de transacciones de la cuenta original se conserva y aún se puede consultar. ## Actualización de Cuentas Virtuales Puede activar o desactivar las cuentas virtuales para controlar el comportamiento de auto-funding. Utilice la [API de Actualizar Cuenta Virtual para wallets maestras](/en/api-reference/virtual-accounts/master-wallet-update) o la [API de Actualizar Cuenta Virtual para direcciones secundarias](/en/api-reference/virtual-accounts/child-address-update). ### **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** | 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" } } ``` 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. ## Webhooks Las cuentas virtuales disparan eventos de webhook cuando se reciben y procesan los pagos. Para las cuentas de tipo `AUTO_FUNDING`, recibirá notificaciones de webhook en cada etapa del flujo de procesamiento del pago. ### **Eventos de Webhook** Cuando un cliente envía un pago en fiat a una cuenta virtual: 1. **`deposit.processing`** - Se dispara inmediatamente al recibir el pago en fiat en la cuenta virtual. Indica que se ha detectado el pago y que el proceso de emisión está por comenzar. 2. **`deposit.success`** - Se dispara cuando la stablecoin se ha emitido y transferido correctamente a la wallet o dirección vinculada. Esto confirma que todo el proceso de auto-funding está completo. 3. **`deposit.failed`** - Se dispara si el proceso de emisión o transferencia falla en algún momento. 4. **`deposit.cancelled`** - Se dispara si la transacción es cancelada 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 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 más información sobre la configuración de webhooks, la estructura del payload y el manejo de eventos, consulte la [documentación de Webhooks](/en/essentials/webhooks). ## Casos de uso ### **Pagos de E-commerce** Cree cuentas virtuales para que los clientes reciban pagos por productos o servicios. La conversión automática a stablecoins permite una integración fluida con su sistema de pagos basado en blockchain. ### **Servicios de suscripción** Vincule cuentas virtuales a las suscripciones de los clientes, permitiendo pagos recurrentes mediante transferencias bancarias tradicionales que se convierten automáticamente en stablecoins. ### **Transacciones de marketplace** Habilite transacciones peer-to-peer donde los clientes pueden enviar 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 NGN, que se convierten automáticamente en stablecoins para facilitar las transferencias transfronterizas. ## Próximos pasos Una vez que tenga cNGN en su wallet: * **[Swap](/en/essentials/swap)** - Convierta cNGN a USDT, USDC u otras stablecoins bajo demanda * **[Auto-Settlement](/en/essentials/auto-settlements)** - Convierta automáticamente cNGN a USDT/USDC en cada depósito ## Buenas prácticas ### **Gestión de cuentas** * **Use el mismo payload de creación en ambas rutas**: La creación de cuentas virtuales para wallet maestra y dirección secundaria utiliza los mismos datos del cliente (`firstname`, `lastname`, `email`, `phone`, `bvn`, `dateOfBirth`) * **Formato del número de teléfono**: Para la creación de cuentas virtuales, utilice siempre el formato correcto (`+234XXXXXXXXXX`) para los números de teléfono nigerianos * **Activación de cuentas**: Active las cuentas únicamente cuando esté listo para procesar pagos * **Monitoree el estado de las cuentas**: Revise regularmente el estado de las cuentas y gestione las cuentas inactivas adecuadamente * **Documente los motivos de regeneración**: Proporcione siempre motivos claros al regenerar cuentas para fines de auditoría ### **Múltiples cuentas** * **Planifique la estructura de sus cuentas**: Decida desde el principio cuántas cuentas puede necesitar cada cliente * **Rastree el historial de cuentas**: Al regenerar, mantenga referencias a los IDs de cuentas anteriores para la conciliación de transacciones ### **Seguridad** * **Verificación del cliente**: Verifique la información del cliente antes de crear cuentas virtuales * **Validación de cuenta**: Valide los datos de la cuenta antes de procesar pagos * **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. Los errores comunes incluyen: | Código de estado | Error | Descripción | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | `400` | Bad Request | Parámetros de solicitud inválidos (por ejemplo, formato de teléfono inválido o detalles de cuenta mal formateados) | | `401` | Unauthorized | Clave de API ausente o inválida | | `404` | Not Found | Cuenta virtual o wallet no encontrada | | `422` | Unprocessable Entity | Validación fallida (por ejemplo, faltan campos requeridos) | ### **Ejemplo de respuesta de error** ```json theme={null} { "message": "Validation failed", "statusCode": 422, "error": "Unprocessable Entity" } ``` ## Soporte * **Email**: [support@blockradar.co](mailto:support@blockradar.co) * **Chat en vivo**: Disponible en el dashboard * **Referencia de la API**: [API de Cuentas Virtuales](/en/api-reference/virtual-accounts/master-wallet-get-all) ¿Necesita soporte para stablecoins o monedas adicionales? Contacte a [support@blockradar.co](mailto:support@blockradar.co).