Virtual Accounts - Blockradar

In a nutshell
Virtual Accounts allow your customers to receive fiat payments through traditional bank transfers, which are automatically converted to stablecoins on the blockchain. You can create multiple virtual accounts per wallet or address, with support for labeling, pagination, and account regeneration.

Prerequisites

Before using the Virtual Accounts API, ensure you have:

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.

Wallet Created

Create a wallet via the Create Wallet API or dashboard. You’ll need the walletId for virtual account operations.

Compliance Approved

Complete the Due Diligence Form (see Compliance Requirements below).

Feature Enabled

Request virtual accounts feature activation after compliance approval. Contact [email protected] or use live chat on the dashboard.

Mainnet Environment

Virtual accounts are only available on MAINNET. Testnet environments do not support virtual account operations.

Stablecoin Support

Ensure your account plan includes stablecoin access. Upgrade from Dashboard → Settings → Subscription if needed.

How It Works

Account Creation

Create virtual accounts linked to master wallets or child addresses with customer information.

Payment Receipt

Customers send fiat payments to the virtual account using traditional bank transfers.

Auto-Funding

Payments automatically trigger minting of the equivalent stablecoin amount.

Fund Management

Minted stablecoins are transferred to the linked wallet or address for immediate use.

Auto-Funding Flow

All virtual accounts use AUTO_FUNDING, which automatically converts fiat to stablecoin. When a customer sends fiat currency to a virtual account:

1. Payment Receipt

The payment is received in the virtual account through traditional bank transfer. A deposit.processing webhook is triggered at this stage.

2. Automatic Minting

The system automatically mints the stablecoin equivalent on the blockchain.

3. Blockchain Transfer

The minted stablecoin is transferred to the virtual account’s linked wallet or address. A deposit.success webhook is triggered upon successful completion.

Compliance Requirements

Before accessing virtual accounts, complete the compliance onboarding process.

Required Documents

Certificate of Incorporation
ID for Directors/Shareholders
KYC Policy Document

Submit Application

Complete the Due Diligence Form with your company details, compliance information, and document uploads.

Supported Currency

Fiat: NGN (Nigerian Naira) - Traditional bank transfers
Stablecoin: cNGN - Minted automatically on blockchain

API Endpoints

Below are the core API endpoints for Virtual Accounts operations:

Master Wallet Endpoints

POST /wallets//virtual-accounts – Create a virtual account for a master wallet
GET /wallets//virtual-accounts – List all virtual accounts (paginated)
GET /wallets//virtual-accounts/ – Retrieve a specific virtual account
GET /wallets//virtual-accounts//transactions – Get transactions for a virtual account
PATCH /wallets//virtual-accounts/ – Update virtual account status
POST /wallets//virtual-accounts//regenerate – Regenerate a virtual account

Child Address Endpoints

POST /wallets//addresses//virtual-accounts – Create a virtual account for a child address
GET /wallets//addresses//virtual-accounts – List all virtual accounts (paginated)
GET /wallets//addresses//virtual-accounts/ – Retrieve a specific virtual account
GET /wallets//addresses//virtual-accounts//transactions – Get transactions for a virtual account
PATCH /wallets//addresses//virtual-accounts/ – Update virtual account status
POST /wallets//addresses//virtual-accounts//regenerate – Regenerate a virtual account

Creating Virtual Accounts

You can create virtual accounts for both master wallets and child addresses, depending on your use case. Use the Create Virtual Account API for master wallets or the Create Virtual Account API for child addresses.

Request Parameters

Parameter	Type	Required	Description
`firstname`	string	Yes	Customer’s first name (max 29 characters)
`lastname`	string	Yes	Customer’s last name (max 29 characters)
`email`	string	Yes	Customer’s email address (must be unique per business)
`phone`	string	No	Customer’s phone number in format: +234XXXXXXXXXX
`label`	string	No	Custom label to identify this virtual account (max 100 characters)

Request Example

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

Response Example

{
  "data": {
    "id": "8180309e-1ead-4a72-a013-b5674600ce4c",
    "accountName": "John Doe",
    "accountNumber": "9018927611",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "type": "AUTO_FUNDING",
    "isActive": true,
    "status": "ACTIVE",
    "label": "Primary Account",
    "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
}

Multiple Virtual Accounts

You can create multiple virtual accounts per wallet or child address. This is useful when:

A customer needs separate accounts for different purposes (e.g., savings, payments)
You want to track payments from different sources separately
A customer’s existing virtual account needs to be replaced while maintaining history

Only one virtual account per customer email can be active at a time. Creating a new virtual account for the same customer email will require deactivating the existing one first, or using the regenerate endpoint.

Listing Virtual Accounts

The list endpoint returns a paginated list of all virtual accounts. Use query parameters to filter and paginate results.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 10)
`isActive`	boolean	Filter by active status (`true` or `false`)

Response Example

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

Retrieving a Single Virtual Account

To retrieve a specific virtual account by ID, use the Get Virtual Account API for master wallets or the Get Virtual Account API for child addresses.

Response Example

{
  "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": "Primary Account",
    "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
  }
}

Virtual Account Transactions

You can retrieve all transactions associated with a specific virtual account using the transactions endpoint.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 10)

Response Example

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

The metadata.autoFunding field contains details about the fiat payment source, including the sender’s bank name, account name, and transaction narration from the bank transfer.

Regenerating Virtual Accounts

The regenerate endpoint allows you to create a new virtual account for a customer while deactivating their existing one. This is useful when:

A customer’s bank account details need to change
The virtual account has been compromised
You need to migrate a customer to a different bank

Regenerate Parameters

Parameter	Type	Required	Description
`firstname`	string	Yes	Customer’s first name (max 29 characters)
`lastname`	string	Yes	Customer’s last name (max 29 characters)
`email`	string	Yes	Customer’s email address
`phone`	string	No	Customer’s phone number in format: +234XXXXXXXXXX
`reason`	string	Yes	Reason for regenerating the virtual account
`label`	string	No	Custom label for the new virtual account

Request Example

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "Customer requested new account number",
  "label": "New Primary Account"
}

The regenerate operation will deactivate the existing virtual account and create a new one. The original account’s transaction history is preserved and can still be queried.

Updating Virtual Accounts

You can activate or deactivate virtual accounts to control auto-funding behavior. Use the Update Virtual Account API for master wallets or the Update Virtual Account API for child addresses.

Auto-Funding Behavior

Active accounts: Payments received trigger automatic stablecoin minting
Inactive accounts: Payments are received but auto-funding is disabled

Update Parameters

Parameter	Type	Required	Description
`isActive`	boolean	Yes	`true` to activate, `false` to deactivate

Request Example

{
  "isActive": false
}

Response Example

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

When a virtual account is deactivated (isActive: false), payments can still be received but the automatic stablecoin minting and transfer process is disabled. You can reactivate the account at any time to re-enable auto-funding.

Webhooks

Virtual accounts trigger webhook events when payments are received and processed. For AUTO_FUNDING type accounts, you’ll receive webhook notifications at each stage of the payment processing flow.

Webhook Events

When a customer sends fiat payment to a virtual account:

deposit.processing - Triggered immediately when the fiat payment is received in the virtual account. This indicates that the payment has been detected and the minting process is about to begin.
deposit.success - Triggered when the stablecoin has been successfully minted and transferred to the linked wallet or address. This confirms that the entire auto-funding process is complete.
deposit.failed - Triggered if the minting or transfer process fails at any point.
deposit.cancelled - Triggered if the transaction is cancelled before completion.

Webhook Payload Example

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

Webhooks are only triggered for active virtual accounts (isActive: true). If an account is deactivated, payments may still be received but webhook events will not be sent until the account is reactivated.

For more information about webhook setup, payload structure, and event handling, see the Webhooks documentation.

Use Cases

E-commerce Payments

Create virtual accounts for customers to receive payments for products or services. The automatic conversion to stablecoins enables seamless integration with your blockchain-based payment system.

Subscription Services

Link virtual accounts to customer subscriptions, allowing recurring payments through traditional bank transfers that are automatically converted to stablecoins.

Marketplace Transactions

Enable peer-to-peer transactions where customers can send fiat payments that are instantly converted to stablecoins and credited to their wallet.

Remittance Services

Provide customers with virtual accounts to receive remittances in NGN, which are automatically converted to stablecoins for easy cross-border transfers.

What’s Next

Once cNGN is in your wallet:

Swap - Convert cNGN to USDT, USDC, or other stablecoins on-demand
Auto-Settlement - Automatically convert cNGN to USDT/USDC on every deposit

Best Practices

Account Management

Use descriptive labels: Add meaningful labels to virtual accounts (e.g., “Savings”, “Payments”) for easy identification
Unique email addresses: Ensure each customer has a unique email address per active account
Phone number format: Always use the correct format (+234XXXXXXXXXX) for Nigerian phone numbers
Account activation: Activate accounts only when ready to process payments
Monitor account status: Regularly check account status and handle inactive accounts appropriately
Document regeneration reasons: Always provide clear reasons when regenerating accounts for audit purposes

Multiple Accounts

Plan your account structure: Decide upfront how many accounts each customer may need
Use labels consistently: Establish a naming convention for labels across your application
Track account history: When regenerating, maintain references to previous account IDs for transaction reconciliation

Security

Customer verification: Verify customer information before creating virtual accounts
Account validation: Validate account details before processing payments
Access control: Implement proper access controls for virtual account management

Error Handling

The API returns standard HTTP status codes and error responses. Common errors include:

Status Code	Error	Description
`400`	Bad Request	Invalid request parameters (e.g., invalid email format, name exceeds 29 characters)
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Virtual account or wallet not found
`409`	Conflict	Email already exists for an active virtual account
`422`	Unprocessable Entity	Validation failed (e.g., missing required fields)

Error Response Example

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

When you receive a 409 error for duplicate email, either deactivate the existing virtual account first or use the regenerate endpoint to create a new account for the same customer.

Support

Email: [email protected]
Live chat: Available on the dashboard
API Reference: Virtual Accounts API

Need support for additional stablecoins or currencies? Contact [email protected].

Get Started

Essentials

​Prerequisites

​How It Works

Account Creation

Payment Receipt

Auto-Funding

Fund Management

​Auto-Funding Flow

​1. Payment Receipt

​2. Automatic Minting

​3. Blockchain Transfer

​Compliance Requirements

​Required Documents

​Submit Application

​Supported Currency

​API Endpoints

​Master Wallet Endpoints

​Child Address Endpoints

​Creating Virtual Accounts

​Request Parameters

​Request Example

​Response Example

​Multiple Virtual Accounts

​Listing Virtual Accounts

​Query Parameters

​Response Example

​Retrieving a Single Virtual Account

​Response Example

​Virtual Account Transactions

​Query Parameters

​Response Example

​Regenerating Virtual Accounts

​Regenerate Parameters

​Request Example

​Updating Virtual Accounts

​Auto-Funding Behavior

​Update Parameters

​Request Example

​Response Example

​Webhooks

​Webhook Events

​Webhook Payload Example

​Use Cases

​E-commerce Payments

​Subscription Services

​Marketplace Transactions

​Remittance Services

​What’s Next

​Best Practices

​Account Management

​Multiple Accounts

​Security

​Error Handling

​Error Response Example

​Support

Prerequisites

How It Works

Auto-Funding Flow

1. Payment Receipt

2. Automatic Minting

3. Blockchain Transfer

Compliance Requirements

Required Documents

Submit Application

Supported Currency

API Endpoints

Master Wallet Endpoints

Child Address Endpoints

Creating Virtual Accounts

Request Parameters

Request Example

Response Example

Multiple Virtual Accounts

Listing Virtual Accounts

Query Parameters

Response Example

Retrieving a Single Virtual Account

Response Example

Virtual Account Transactions

Query Parameters

Response Example

Regenerating Virtual Accounts

Regenerate Parameters

Request Example

Updating Virtual Accounts

Auto-Funding Behavior

Update Parameters

Request Example

Response Example

Webhooks

Webhook Events

Webhook Payload Example

Use Cases

E-commerce Payments

Subscription Services

Marketplace Transactions

Remittance Services

What’s Next

Best Practices

Account Management

Multiple Accounts

Security

Error Handling

Error Response Example

Support