Deposit Fiat - Blockradar

v2 · Recommended
v1 · Legacy

In a nutshell
Virtual Accounts let your customers receive fiat through traditional bank transfers, which are automatically converted to stablecoins on the blockchain. The v2 flow discovers the assets and currencies available to your wallet, returns a schema describing exactly what each corridor requires, and creates virtual accounts linked to a master wallet or child address across multiple currencies and stablecoins.

v2 requirements return a JSON Schema describing the information a corridor needs. When additionalDataRequired is true, use the Dynamic Forms guide to collect, validate, and submit the fields as additionalData. The v1 flow is available in the v1 · Legacy tab, but is no longer recommended.

Prerequisites

Before using Virtual Accounts, 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 a Master Wallet guide or dashboard. You’ll need the walletId for virtual account operations.

Compliance Approved

Complete the Due Diligence process on the Dashboard: My Wallets → Settings → Compliance. Compliance requirements and approval processes vary by geography, so you only need to complete the ones for the local rails your product uses.

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

Depositing fiat and converting it to a stablecoin is a paid feature. Ensure your plan includes stablecoin access. Upgrade from Dashboard → Settings → Subscription.

How It Works

Discover Options

Fetch the assets and currencies available to your wallet.

Get Requirements

Retrieve the schema describing what the selected corridor needs.

Create Account

Create a virtual account with additionalData and an optional label.

Auto-Funding

Incoming fiat automatically mints the equivalent stablecoin to the linked wallet or address.

Supported Fiat Currencies

Currencies vary by corridor and provider. Always fetch what’s available to your wallet with the discovery endpoint rather than hard-coding the list. The table below shows the stablecoins and blockchains each supported currency covers:

Fiat Currency	USDC Blockchains	USDT Blockchains	EURC Blockchains
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

Auto-Funding Flow

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

1. Payment Receipt

The payment is received in the virtual account through a 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.

Supported Assets and Currencies

v2 supports multiple stablecoins and currencies. Rather than assuming a fixed pair, fetch what’s available to your wallet with the discovery endpoint. For example, NGN bank transfers can auto-fund cNGN, while other corridors settle to USDC or other supported assets.

API Endpoints

Master Wallet Endpoints

Operation	Endpoint
Discover options	`GET /v2/wallets/{id}/virtual-accounts/discovery`
Get requirements	`GET /v2/wallets/{id}/virtual-accounts/requirements`
Create	`POST /v2/wallets/{id}/virtual-accounts`
List	`GET /v2/wallets/{id}/virtual-accounts`
Get one	`GET /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Update status	`PATCH /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Regenerate	`POST /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/regenerate`

Child Address Endpoints

Operation	Endpoint
Create	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
List	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Get one	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Transactions	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions`
Update status	`PATCH /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Regenerate	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate`

Step 1: Discover Options

Fetch the assets and currencies available to your wallet for virtual accounts.

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

Step 2: Get Requirements

Fetch the schema describing what the selected currency (and optionally asset) requires. Interpret and complete it with Dynamic Forms.

Parameter	In	Required	Description
`currency`	query	Yes	ISO 4217 currency code
`assetId`	query	No	Stablecoin asset that receives settlements
`customerId`	query	No	Existing customer identifier, when the provider requires one
`provider`	query	No	Provider slug. Omit to let Blockradar route automatically

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

If additionalDataRequired is false, you can skip collecting additionalData and create the account directly. Use the provider returned here when you create the account.

Step 3: Create a Virtual Account

Create a virtual account for a master wallet or child address. Send the validated additionalData object built from the requirements schema.

Parameter	Type	Required	Description
`provider`	string	Yes	Provider slug resolved from the requirements flow
`currency`	string	Yes	ISO 4217 virtual-account currency
`assetId`	string	No	Stablecoin asset that receives settlements
`customerId`	string	No	Existing customer identifier, when the provider requires one
`additionalData`	object	No	Values collected and validated against `additionalDataSchema`
`label`	string	No	Your display label for the virtual account (max 100 chars)

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

Response Example

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

Listing Virtual Accounts

The list endpoint returns a paginated list of virtual accounts. Use query parameters to search, filter by activation state, and filter by date range.

Query Parameters

Parameter	Type	Description
`isActive`	boolean	Filter by activation state (`true` or `false`)
`search`	string	Search by reference, label, account name, or account number
`startDate`	string	Inclusive ISO 8601 start date. Required only when `endDate` is supplied
`endDate`	string	Inclusive ISO 8601 end date. Required only when `startDate` is supplied
`page`	integer	One-based page number (default: 1)
`limit`	integer	Records per page, max 100 (default: 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
  }
}

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.

Virtual Account Transactions

Retrieve the transactions associated with a virtual account using the child address transactions endpoint. Every auto-funding event is also delivered via webhooks.

Query Parameters

Parameter	Type	Description
`page`	integer	One-based page number (default: 1)
`limit`	integer	Records per page, max 100 (default: 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
  }
}

Updating Virtual Accounts

Activate or deactivate a virtual account 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
}

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.

Regenerating Virtual Accounts

The regenerate endpoint creates a new virtual account for a customer while deactivating the 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 provider

Regenerate Parameters

Parameter	Type	Required	Description
`provider`	string	Yes	Provider slug for the replacement account
`currency`	string	Yes	ISO 4217 virtual-account currency
`reason`	string	Yes	Reason a replacement account is required
`assetId`	string	No	Stablecoin asset that receives settlements
`customerId`	string	No	Existing customer identifier
`additionalData`	object	No	Values validated against the requirements schema
`label`	string	No	Your display label for the virtual account

Request Example

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

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

Webhooks

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

Webhook Events

deposit.processing — Triggered immediately when the fiat payment is received. The minting process is about to begin.
deposit.success — Triggered when the stablecoin has been minted and transferred to the linked wallet or address.
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",
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "accountNumber": "0123456789",
      "bankName": "Example Bank"
    },
    "wallet": {
      "id": "4465468a-3c36-4536-918a-91d689e18a74",
      "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 webhook setup, payload structure, and event handling, see the Webhooks documentation.

What’s Next

Once the stablecoin is in your wallet:

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

Use Cases

E-commerce Payments

Create virtual accounts for customers to receive payments for products or services, automatically converted to stablecoins for your blockchain-based payment system.

Subscription Services

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

Marketplace Transactions

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

Remittance Services

Provide customers with virtual accounts to receive local-currency remittances, automatically converted to stablecoins for cross-border transfers.

Best Practices

Account Management

Use the requirements schema: Collect only the fields in the current requirements schema. Do not hard-code onboarding fields — see Dynamic Forms.
Reuse the returned provider: Create with the provider returned by the requirements request.
Label your accounts: Set a label to make accounts searchable and easy to reconcile.
Account activation: Deactivate accounts you are not ready to fund; reactivate when ready.
Document regeneration reasons: Always provide a clear reason when regenerating for audit purposes.

Security

Customer verification: Verify customer information before creating virtual accounts.
Preserve strings: Send identifiers and codes as strings to avoid precision loss.
Access control: Implement proper access controls for virtual account management.

Error Handling

The API returns standard HTTP status codes and error responses.

Status Code	Error	Description
`400`	Bad Request	Invalid request parameters or malformed `additionalData`
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Virtual account or wallet not found
`422`	Unprocessable Entity	Validation failed (e.g., missing required fields)

Error Response Example

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

API Reference

v2 (Recommended)

Endpoint	Description
Discover Options	List available assets and currencies
Get Requirements	Fetch the fields schema for a corridor
Master Wallet Create	Create a virtual account for a master wallet
Master Wallet List	List virtual accounts for a master wallet
Master Wallet Get One	Retrieve a specific virtual account
Master Wallet Update	Activate or deactivate a virtual account
Master Wallet Regenerate	Regenerate a virtual account
Child Address Create	Create a virtual account for a child address
Child Address List	List virtual accounts for a child address
Child Address Get One	Retrieve a specific virtual account
Child Address Transactions	List transactions for a virtual account
Child Address Update	Activate or deactivate a virtual account
Child Address Regenerate	Regenerate a virtual account

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

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 pagination and account regeneration.

Virtual account requirements can vary by provider, currency, and customer. When an endpoint returns a form schema, use the Dynamic Forms guide to collect and validate the required information.

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 process on the Dashboard: My wallets > Settings > Compliance

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

Depositing Fiat and converting it to a stablecoin is a paid feature. Ensure your account plan includes stablecoin access. Upgrade from Dashboard → Settings → Subscription.

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.

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.

Master Wallet 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
`bvn`	string	Yes	Customer’s Bank Verification Number
`dateOfBirth`	string	Yes	Customer’s date of birth in `yyyy-MM-dd` format

Master Wallet Request Example

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

Child Address 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
`bvn`	string	Yes	Customer’s Bank Verification Number
`dateOfBirth`	string	Yes	Customer’s date of birth in `yyyy-MM-dd` format

Child Address Request Example

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

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

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

Request Example

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

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

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

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 the same create payload across both routes: Master wallet and child address virtual account creation both use customer details (firstname, lastname, email, phone, bvn, dateOfBirth)
Phone number format: For virtual account creation, 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
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 phone format or malformed account details)
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Virtual account or wallet not found
`422`	Unprocessable Entity	Validation failed (e.g., missing required fields)

Error Response Example

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

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

​Prerequisites

​How It Works

Discover Options

Get Requirements

Create Account

Auto-Funding

​Supported Fiat Currencies

​Auto-Funding Flow

​1. Payment Receipt

​2. Automatic Minting

​3. Blockchain Transfer

​Supported Assets and Currencies

​API Endpoints

​Master Wallet Endpoints

​Child Address Endpoints

​Step 1: Discover Options

​Step 2: Get Requirements

​Step 3: Create a Virtual Account

​Response Example

​Listing Virtual Accounts

​Query Parameters

​Retrieving a Single Virtual Account

​Virtual Account Transactions

​Query Parameters

​Updating Virtual Accounts

​Auto-Funding Behavior

​Update Parameters

​Regenerating Virtual Accounts

​Regenerate Parameters

​Webhooks

​Webhook Events

​Webhook Payload Example

​What’s Next

​Use Cases

​E-commerce Payments

​Subscription Services

​Marketplace Transactions

​Remittance Services

​Best Practices

​Account Management

​Security

​Error Handling

​Error Response Example

​API Reference

​v2 (Recommended)

​Support

​Prerequisites

​How It Works

Account Creation

Payment Receipt

Auto-Funding

Fund Management

​Auto-Funding Flow

​1. Payment Receipt

​2. Automatic Minting

​3. Blockchain Transfer

​Supported Currency

​API Endpoints

​Master Wallet Endpoints

​Child Address Endpoints

​Creating Virtual Accounts

​Master Wallet Request Parameters

​Master Wallet Request Example

​Child Address Request Parameters

​Child Address 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

Prerequisites

How It Works

Supported Fiat Currencies

Auto-Funding Flow

1. Payment Receipt

2. Automatic Minting

3. Blockchain Transfer

Supported Assets and Currencies

API Endpoints

Master Wallet Endpoints

Child Address Endpoints

Step 1: Discover Options

Step 2: Get Requirements

Step 3: Create a Virtual Account

Response Example

Listing Virtual Accounts

Query Parameters

Retrieving a Single Virtual Account

Virtual Account Transactions

Query Parameters

Updating Virtual Accounts

Auto-Funding Behavior

Update Parameters

Regenerating Virtual Accounts

Regenerate Parameters

Webhooks

Webhook Events

Webhook Payload Example

What’s Next

Use Cases

E-commerce Payments

Subscription Services

Marketplace Transactions

Remittance Services

Best Practices

Account Management

Security

Error Handling

Error Response Example

API Reference

v2 (Recommended)

Support

Prerequisites

How It Works

Auto-Funding Flow

1. Payment Receipt

2. Automatic Minting

3. Blockchain Transfer

Supported Currency

API Endpoints

Master Wallet Endpoints

Child Address Endpoints

Creating Virtual Accounts

Master Wallet Request Parameters

Master Wallet Request Example

Child Address Request Parameters

Child Address 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