Skip to main content
Virtual Accounts API provides endpoints for managing virtual bank accounts linked to master wallets or child addresses. This API enables businesses to create virtual accounts for customers to receive payments, retrieve virtual account details, and activate/deactivate virtual accounts.

​
Introduction

Virtual Accounts allow your customers to receive fiat payments through traditional bank transfers, which are automatically converted to stablecoins on the blockchain. This bridges the gap between traditional banking and stablecoin payments, enabling seamless payment processing for your business. When a customer sends fiat currency to a virtual account, the system can automatically mint the stablecoin equivalent and transfer it to the linked wallet or address, providing real-time payment processing capabilities.

​
How Virtual Accounts Work

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

For AUTO_FUNDING type accounts, payments automatically trigger minting of the stablecoin.

Fund Management

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

​
Virtual Account Types

Virtual accounts support different types with varying behaviors:

​
AUTO_FUNDING (Default)

  • Automatically mints stablecoin when fiat payments are received
  • Transfers stablecoin to the linked wallet/address immediately
  • Best for real-time payment processing
  • Provides instant conversion from fiat to stablecoin
The auto-funding flow only applies to virtual accounts with type AUTO_FUNDING. Other types have different processing behaviors.

​
How It Works - Auto-Funding Flow

When a customer sends fiat currency to a virtual account with type AUTO_FUNDING:

​
1. Payment Receipt

The payment is received in the virtual account through traditional bank transfer.

​
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.
The auto-funding flow only applies to virtual accounts with type AUTO_FUNDING. Other types have different processing behaviors.

​
Prerequisites

Before creating virtual accounts, ensure:
  • Virtual accounts feature must be enabled for your business(reach out to [email protected] to enable the feature)
  • Only available on MAINNET environment (not available on testnet)
  • Master Wallet must support stablecoin asset
Environment: Virtual accounts are only available in the MAINNET environment. Testnet environments do not support virtual account creation or operations.

​
Supported Currency

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

​
API Endpoints

Below are the core API endpoints for Virtual Accounts operations:

​
Master Wallet Endpoints

​
Child Address Endpoints

​
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

ParameterTypeRequiredDescription
firstnamestringYesCustomer’s first name
lastnamestringYesCustomer’s last name
emailstringYesCustomer’s email address (must be unique per business)
phonestringYesCustomer’s phone number in format: +234XXXXXXXXXX

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

​
Retrieving Virtual Accounts

To retrieve virtual account details, use the Get Virtual Account API for master wallets or the Get Virtual Account API for child addresses.

​
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

ParameterTypeRequiredDescription
isActivebooleanYestrue to activate, false to deactivate
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.

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

​
Best Practices

​
Account Management

  • Unique email addresses: Ensure each customer has a unique email address
  • 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

​
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

​
Support & Resources

​
Getting Help

Virtual accounts provide a powerful way to bridge traditional banking with blockchain payments. Start by creating accounts for your master wallets, then expand to child addresses as your use case requires. Always ensure your wallets support stablecoin for AUTO_FUNDING type accounts.


Happy hacking! ❤️