Depositar Fiat - Blockradar

v2 · Recomendado
v1 · Legacy

En resumen
Las Cuentas Virtuales permiten que sus clientes reciban moneda fiat mediante transferencias bancarias tradicionales, que se convierten automáticamente en stablecoins en la blockchain. El flujo v2 descubre los activos y las monedas disponibles para su wallet, devuelve un esquema que describe exactamente lo que requiere cada corredor, y crea cuentas virtuales vinculadas a una master wallet o child address en múltiples monedas y stablecoins.

Los requisitos v2 devuelven un JSON Schema que describe la información que necesita un corredor. Cuando additionalDataRequired es true, utilice la guía de Formularios dinámicos para recopilar, validar y enviar los campos como additionalData. El flujo v1 está disponible en la pestaña v1 · Legacy, pero ya no se recomienda.

Requisitos previos

Antes de utilizar las 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 guía Crear una Master Wallet o desde el dashboard. Necesitará el walletId para las operaciones con cuentas virtuales.

Cumplimiento aprobado

Complete el proceso de Diligencia Debida en el Dashboard: My Wallets → Settings → Compliance. Los requisitos de cumplimiento y los procesos de aprobación varían según la región, por lo que solo necesita completar los correspondientes a los rieles locales que utilice su producto.

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 incluya acceso a stablecoins. Actualice desde Dashboard → Settings → Subscription.

Cómo funciona

Descubrir opciones

Consulte los activos y las monedas disponibles para su wallet.

Obtener requisitos

Recupere el esquema que describe lo que necesita el corredor seleccionado.

Crear cuenta

Cree una cuenta virtual con additionalData y un label opcional.

Auto-Funding

El fiat entrante emite automáticamente la stablecoin equivalente en la wallet o dirección vinculada.

Monedas fiat compatibles

Las monedas varían según el corredor y el proveedor. Consulte siempre lo que está disponible para su wallet con el endpoint de descubrimiento en lugar de codificar la lista de forma fija. La tabla a continuación muestra las stablecoins y blockchains que cubre cada moneda compatible:

Moneda Fiat	Blockchains USDC	Blockchains USDT	Blockchains EURC
COP	Ethereum, Polygon	Ethereum	—
GHS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
INR	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
KES	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
NGN	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
TZS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
UGX	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base

Flujo de Auto-Funding

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

1. Recepción del pago

El pago se recibe en la cuenta virtual mediante una transferencia bancaria. 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.

Activos y monedas compatibles

v2 admite múltiples stablecoins y monedas. En lugar de asumir un par fijo, consulte lo que está disponible para su wallet con el endpoint de descubrimiento. Por ejemplo, las transferencias bancarias en NGN pueden auto-fondear cNGN, mientras que otros corredores se liquidan en USDC u otros activos compatibles.

Endpoints de la API

Endpoints de Wallet Maestra

Operación	Endpoint
Descubrir opciones	`GET /v2/wallets/{id}/virtual-accounts/discovery`
Obtener requisitos	`GET /v2/wallets/{id}/virtual-accounts/requirements`
Crear	`POST /v2/wallets/{id}/virtual-accounts`
Listar	`GET /v2/wallets/{id}/virtual-accounts`
Obtener una	`GET /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Actualizar estado	`PATCH /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Regenerar	`POST /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/regenerate`

Endpoints de Dirección Secundaria

Operación	Endpoint
Crear	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Listar	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Obtener una	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Transacciones	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions`
Actualizar estado	`PATCH /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Regenerar	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate`

Paso 1: Descubrir opciones

Consulte los activos y las monedas disponibles para su wallet para cuentas virtuales.

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/discovery' \
  --header 'x-api-key: <api-key>'

Discovery Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "assets": [
      {
        "asset": {
          "id": "ae455f23-3824-4125-baab-d158315cbcbd",
          "name": "USD Coin",
          "symbol": "USDC",
          "logoUrl": "https://cdn.example.com/assets/usdc.svg",
          "blockchain": {
            "id": "7773c3f9-f35d-4a36-9d85-5f4c537cd097",
            "name": "Ethereum",
            "symbol": "ETH",
            "slug": "ethereum",
            "tokenStandard": "ERC20",
            "logoUrl": "https://cdn.example.com/blockchains/ethereum.svg"
          }
        },
        "currencies": ["NGN"]
      }
    ],
    "currencies": {
      "NGN": {
        "code": "NGN",
        "currency": "NGN",
        "shortName": "Naira",
        "name": "Nigerian Naira",
        "symbol": "₦"
      }
    }
  }
}

Paso 2: Obtener requisitos

Consulte el esquema que describe lo que requiere la moneda seleccionada (y opcionalmente el activo). Interprételo y complételo con Formularios dinámicos.

Parámetro	En	Requerido	Descripción
`currency`	query	Sí	Código de moneda ISO 4217
`assetId`	query	No	Activo stablecoin que recibe las liquidaciones
`customerId`	query	No	Identificador de cliente existente, cuando el proveedor lo requiere
`provider`	query	No	Slug del proveedor. Omítalo para que Blockradar enrute automáticamente

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/requirements?currency=NGN&assetId=ae455f23-3824-4125-baab-d158315cbcbd' \
  --header 'x-api-key: <api-key>'

Requirements Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "supported": true,
    "unlocked": true,
    "additionalDataRequired": true,
    "additionalDataSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Bank account details",
      "properties": {
        "bvn": { "type": "string", "title": "BVN", "minLength": 11, "maxLength": 11 },
        "dateOfBirth": { "type": "string", "title": "Date of birth", "format": "date" }
      },
      "required": ["bvn", "dateOfBirth"],
      "additionalProperties": false
    },
    "provider": "example-provider"
  }
}

Si additionalDataRequired es false, puede omitir la recopilación de additionalData y crear la cuenta directamente. Use el provider devuelto aquí al crear la cuenta.

Paso 3: Crear una cuenta virtual

Cree una cuenta virtual para una master wallet o child address. Envíe el objeto additionalData validado construido a partir del esquema de requisitos.

Parámetro	Tipo	Requerido	Descripción
`provider`	string	Sí	Slug del proveedor resuelto en el flujo de requisitos
`currency`	string	Sí	Moneda ISO 4217 de la cuenta virtual
`assetId`	string	No	Activo stablecoin que recibe las liquidaciones
`customerId`	string	No	Identificador de cliente existente, cuando el proveedor lo requiere
`additionalData`	object	No	Valores recopilados y validados contra `additionalDataSchema`
`label`	string	No	Su etiqueta visible para la cuenta virtual (máximo 100 caracteres)

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

Ejemplo de respuesta

{
  "statusCode": 201,
  "message": "Virtual account created successfully",
  "data": {
    "created": true,
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  }
}

Listado de cuentas virtuales

El endpoint de listado devuelve una lista paginada de cuentas virtuales. Utilice los parámetros de consulta para buscar, filtrar por estado de activación y filtrar por rango de fechas.

Parámetros de consulta

Parámetro	Tipo	Descripción
`isActive`	boolean	Filtrar por estado de activación (`true` o `false`)
`search`	string	Buscar por referencia, etiqueta, nombre de cuenta o número de cuenta
`startDate`	string	Fecha de inicio ISO 8601 inclusiva. Requerida solo cuando se proporciona `endDate`
`endDate`	string	Fecha de fin ISO 8601 inclusiva. Requerida solo cuando se proporciona `startDate`
`page`	integer	Número de página basado en 1 (predeterminado: 1)
`limit`	integer	Registros por página, máximo 100 (predeterminado: 10)

Response Example

{
  "statusCode": 200,
  "message": "Virtual accounts retrieved successfully",
  "data": [
    {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

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.

Transacciones de cuenta virtual

Obtenga las transacciones asociadas a una cuenta virtual usando el endpoint de transacciones de dirección secundaria. Cada evento de auto-funding también se entrega mediante webhooks.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página basado en 1 (predeterminado: 1)
`limit`	integer	Registros por página, máximo 100 (predeterminado: 10)

Response Example

{
  "statusCode": 200,
  "message": "Virtual account transactions retrieved successfully",
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "50.0",
      "rateUSD": "1.0",
      "currency": "NGN",
      "hash": "0xbe0c9a4dd314b6220c4eaae218003e753e948ce6183b5b92c764501e1b4e7c0a",
      "confirmed": true,
      "status": "SUCCESS",
      "processingStatus": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN",
      "createdAt": "2026-01-22T22:29:28.679Z",
      "updatedAt": "2026-01-22T23:15:21.849Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

Actualización de cuentas virtuales

Active o desactive una cuenta virtual 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

Request Example

{
  "isActive": false
}

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.

Regeneración de cuentas virtuales

El endpoint de regeneración crea una nueva cuenta virtual para un cliente mientras desactiva la existente. Esto es útil cuando:

Los datos bancarios de un cliente deben cambiar
La cuenta virtual ha sido comprometida
Necesita migrar a un cliente a un proveedor diferente

Parámetros de regeneración

Parámetro	Tipo	Requerido	Descripción
`provider`	string	Sí	Slug del proveedor para la cuenta de reemplazo
`currency`	string	Sí	Moneda ISO 4217 de la cuenta virtual
`reason`	string	Sí	Motivo por el que se requiere una cuenta de reemplazo
`assetId`	string	No	Activo stablecoin que recibe las liquidaciones
`customerId`	string	No	Identificador de cliente existente
`additionalData`	object	No	Valores validados contra el esquema de requisitos
`label`	string	No	Su etiqueta visible para la cuenta virtual

Request Example

{
  "provider": "example-provider",
  "currency": "NGN",
  "reason": "The previous account was closed by the institution.",
  "label": "Ada collection account"
}

La operación de regeneración desactiva la cuenta virtual existente y crea una nueva. El historial de transacciones de la cuenta original se conserva y aún se puede consultar.

Webhooks

Las cuentas virtuales disparan eventos de webhook cuando se reciben y procesan los pagos. Para las cuentas de tipo AUTO_FUNDING, recibirá notificaciones en cada etapa del flujo de pago.

Eventos de Webhook

deposit.processing — Se dispara inmediatamente al recibir el pago en fiat. El proceso de emisión está por comenzar.
deposit.success — Se dispara cuando la stablecoin se ha emitido y transferido a la wallet o dirección vinculada.
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",
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "accountNumber": "0123456789",
      "bankName": "Example Bank"
    },
    "wallet": {
      "id": "4465468a-3c36-4536-918a-91d689e18a74",
      "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 la configuración de webhooks, la estructura del payload y el manejo de eventos, consulte la documentación de Webhooks.

Próximos pasos

Una vez que la stablecoin esté en su wallet:

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

Casos de uso

Pagos de E-commerce

Cree cuentas virtuales para que los clientes reciban pagos por productos o servicios, convertidos automáticamente en stablecoins para su sistema de pagos basado en blockchain.

Servicios de suscripción

Vincule cuentas virtuales a las suscripciones de los clientes, permitiendo transferencias bancarias recurrentes que se convierten automáticamente en stablecoins.

Transacciones de marketplace

Habilite transacciones donde los clientes envían 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 moneda local, convertidas automáticamente en stablecoins para transferencias transfronterizas.

Buenas prácticas

Gestión de cuentas

Use el esquema de requisitos: Recopile solo los campos del esquema de requisitos actual. No codifique de forma fija los campos de incorporación — consulte Formularios dinámicos.
Reutilice el proveedor devuelto: Cree con el provider devuelto por la solicitud de requisitos.
Etiquete sus cuentas: Establezca un label para que las cuentas sean buscables y fáciles de conciliar.
Activación de cuentas: Desactive las cuentas que no esté listo para fondear; reactívelas cuando esté listo.
Documente los motivos de regeneración: Proporcione siempre un reason claro al regenerar para fines de auditoría.

Seguridad

Verificación del cliente: Verifique la información del cliente antes de crear cuentas virtuales.
Preserve las cadenas: Envíe los identificadores y códigos como cadenas para evitar la pérdida de precisión.
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.

Código de estado	Error	Descripción
`400`	Bad Request	Parámetros de solicitud inválidos o `additionalData` mal formateado
`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

{
  "statusCode": 400,
  "message": "Invalid additional data for bvn: bvn does not match the expected format"
}

Referencia de API

v2 (recomendado)

Endpoint	Descripción
Discover Options	Listar los activos y monedas disponibles
Get Requirements	Consultar el esquema de campos de un corredor
Master Wallet Create	Crear una cuenta virtual para una wallet maestra
Master Wallet List	Listar cuentas virtuales de una wallet maestra
Master Wallet Get One	Obtener una cuenta virtual específica
Master Wallet Update	Activar o desactivar una cuenta virtual
Master Wallet Regenerate	Regenerar una cuenta virtual
Child Address Create	Crear una cuenta virtual para una dirección secundaria
Child Address List	Listar cuentas virtuales de una dirección secundaria
Child Address Get One	Obtener una cuenta virtual específica
Child Address Transactions	Listar transacciones de una cuenta virtual
Child Address Update	Activar o desactivar una cuenta virtual
Child Address Regenerate	Regenerar una cuenta virtual

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

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 proceso de Diligencia Debida en el Panel: My wallets > Settings > Compliance

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.

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

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

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

​Requisitos previos

​Cómo funciona

Descubrir opciones

Obtener requisitos

Crear cuenta

Auto-Funding

​Monedas fiat compatibles

​Flujo de Auto-Funding

​1. Recepción del pago

​2. Emisión automática

​3. Transferencia en blockchain

​Activos y monedas compatibles

​Endpoints de la API

​Endpoints de Wallet Maestra

​Endpoints de Dirección Secundaria

​Paso 1: Descubrir opciones

​Paso 2: Obtener requisitos

​Paso 3: Crear una cuenta virtual

​Ejemplo de respuesta

​Listado de cuentas virtuales

​Parámetros de consulta

​Obtener una cuenta virtual específica

​Transacciones de cuenta virtual

​Parámetros de consulta

​Actualización de cuentas virtuales

​Comportamiento de Auto-Funding

​Parámetros de actualización

​Regeneración de cuentas virtuales

​Parámetros de regeneración

​Webhooks

​Eventos de Webhook

​Ejemplo de payload de Webhook

​Próximos pasos

​Casos de uso

​Pagos de E-commerce

​Servicios de suscripción

​Transacciones de marketplace

​Servicios de remesas

​Buenas prácticas

​Gestión de cuentas

​Seguridad

​Manejo de errores

​Ejemplo de respuesta de error

​Referencia de API

​v2 (recomendado)

​Soporte

​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

​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

Requisitos previos

Cómo funciona

Monedas fiat compatibles

Flujo de Auto-Funding

1. Recepción del pago

2. Emisión automática

3. Transferencia en blockchain

Activos y monedas compatibles

Endpoints de la API

Endpoints de Wallet Maestra

Endpoints de Dirección Secundaria

Paso 1: Descubrir opciones

Paso 2: Obtener requisitos

Paso 3: Crear una cuenta virtual

Ejemplo de respuesta

Listado de cuentas virtuales

Parámetros de consulta

Obtener una cuenta virtual específica

Transacciones de cuenta virtual

Parámetros de consulta

Actualización de cuentas virtuales

Comportamiento de Auto-Funding

Parámetros de actualización

Regeneración de cuentas virtuales

Parámetros de regeneración

Webhooks

Eventos de Webhook

Ejemplo de payload de Webhook

Próximos pasos

Casos de uso

Pagos de E-commerce

Servicios de suscripción

Transacciones de marketplace

Servicios de remesas

Buenas prácticas

Gestión de cuentas

Seguridad

Manejo de errores

Ejemplo de respuesta de error

Referencia de API

v2 (recomendado)

Soporte

Requisitos previos

Cómo funciona

Flujo de Auto-Funding

1. Recepción del pago

2. Emisión automática

3. Transferencia en blockchain

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