Depositar Fiat - Blockradar

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.

Requisitos previos

Antes de utilizar la API de Cuentas Virtuales, asegúrese de contar con:

Clave de API

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

Wallet creada

Cree una wallet mediante la API de Crear Wallet o desde el dashboard. Necesitará el walletId para las operaciones con cuentas virtuales.

Cumplimiento aprobado

Complete el Formulario de Diligencia Debida (consulte los Requisitos de Cumplimiento más abajo).

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.

Entorno Mainnet

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

Soporte de stablecoin

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

Creación de cuenta

Cree cuentas virtuales vinculadas a wallets maestras o direcciones secundarias con la información del cliente.

Recepción de pago

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

Auto-Funding

Los pagos activan automáticamente la emisión del importe equivalente en stablecoin.

Gestión de fondos

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 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//virtual-accounts – Crear una cuenta virtual para una wallet maestra
GET /wallets//virtual-accounts – Listar todas las cuentas virtuales (paginado)
GET /wallets//virtual-accounts/ – Obtener una cuenta virtual específica
GET /wallets//virtual-accounts//transactions – Obtener transacciones de una cuenta virtual
PATCH /wallets//virtual-accounts/ – Actualizar el estado de una 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/ – Obtener una cuenta virtual específica
GET /wallets//addresses//virtual-accounts//transactions – Obtener transacciones de una cuenta virtual
PATCH /wallets//addresses//virtual-accounts/ – Actualizar el estado de una cuenta virtual
POST /wallets//addresses//virtual-accounts//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 para wallets maestras o la API de Crear Cuenta Virtual para direcciones secundarias.

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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "bvn": "22345678901",
  "dateOfBirth": "1992-08-14"
}

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
}

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

{
  "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": "[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
  }
}

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.

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",
    "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

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

{
  "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

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "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 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

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"
  }
}

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:

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.
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.
deposit.failed - Se dispara si el proceso de emisión o transferencia falla en algún momento.
deposit.cancelled - Se dispara si la transacción es cancelada 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 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.

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 - Convierta cNGN a USDT, USDC u otras stablecoins bajo demanda
Auto-Settlement - 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

{
  "message": "Validation failed",
  "statusCode": 422,
  "error": "Unprocessable Entity"
}

Soporte

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

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

Comenzar

Billeteras

Recibir Pagos

Enviar Pagos

Convertir y Gestionar

Cumplimiento y Recuperación

Integraciones

Documentation Index

​Requisitos previos

​Cómo funciona

Creación de cuenta

Recepción de pago

Auto-Funding

Gestión de fondos

​Flujo de Auto-Funding

​1. Recepción del pago

​2. Emisión automática

​3. Transferencia en blockchain

​Requisitos de cumplimiento

​Documentos requeridos

​Enviar solicitud

​Moneda admitida

​Endpoints de la API

​Endpoints de Wallet Maestra

​Endpoints de Dirección Secundaria

​Creación de Cuentas Virtuales

​Parámetros de solicitud para Wallet Maestra

​Ejemplo de solicitud para Wallet Maestra

​Parámetros de solicitud para Dirección Secundaria

​Ejemplo de solicitud para Dirección Secundaria

​Ejemplo de respuesta

​Múltiples Cuentas Virtuales

​Listado de Cuentas Virtuales

​Parámetros de consulta

​Ejemplo de respuesta

​Obtener una Cuenta Virtual específica

​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 de Auto-Funding

​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 E-commerce

​Servicios de suscripción

​Transacciones de marketplace

​Servicios de remesas

​Próximos pasos

​Buenas 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 Auto-Funding

1. Recepción del pago

2. Emisión automática

3. Transferencia en blockchain

Requisitos de cumplimiento

Documentos requeridos

Enviar solicitud

Moneda admitida

Endpoints de la API

Endpoints de Wallet Maestra

Endpoints de Dirección Secundaria

Creación de Cuentas Virtuales

Parámetros de solicitud para Wallet Maestra

Ejemplo de solicitud para Wallet Maestra

Parámetros de solicitud para Dirección Secundaria

Ejemplo de solicitud para Dirección Secundaria

Ejemplo de respuesta

Múltiples Cuentas Virtuales

Listado de Cuentas Virtuales

Parámetros de consulta

Ejemplo de respuesta

Obtener una Cuenta Virtual específica

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 de Auto-Funding

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 E-commerce

Servicios de suscripción

Transacciones de marketplace

Servicios de remesas

Próximos pasos

Buenas prácticas

Gestión de cuentas

Múltiples cuentas

Seguridad

Manejo de errores

Ejemplo de respuesta de error

Soporte