Skip to main content

​
What are Virtual Accounts?

Virtual accounts are unique bank account numbers that you can generate on-demand for your customers. Each virtual account is tied to your main settlement account but appears as a unique account number to your customers.
Virtual accounts enable you to accept payments without requiring customers to specify reference codes, making collections seamless and automatic.

​
Key Benefits

Automatic Reconciliation

Each customer gets a unique account number, so payments are automatically matched to the right customer.

Better User Experience

Customers just transfer to their account number - no reference codes needed.

Instant Notifications

Get real-time webhooks whenever a payment is received.

Unlimited Creation

Create as many virtual accounts as you need at no extra cost.

​
How Virtual Accounts Work

​
Virtual Account Types

​
Dedicated Virtual Accounts

Permanent account numbers assigned to specific customers. Best for:
  • Long-term customer relationships
  • Subscription businesses
  • Wallets and balance top-ups
  • Regular collections
{
  "type": "dedicated",
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "customer_phone": "+2348012345678"
}

​
Temporary Virtual Accounts

Short-lived account numbers for one-time or time-limited payments. Best for:
  • Invoice payments
  • E-commerce checkouts
  • Event tickets
  • Time-sensitive collections
{
  "type": "temporary",
  "customer_name": "Jane Smith",
  "expires_at": "2024-01-31T23:59:59Z",
  "amount": 50000
}

​
Virtual Account Lifecycle

1

Creation

Generate a virtual account via the API or dashboard
2

Active

Account is ready to receive payments
3

Payment Received

Customer transfers money to the account
4

Settlement

Funds are settled to your main account (instant or scheduled)
5

Expiry (Optional)

Temporary accounts expire after the set duration

​
Settlement Options

Choose how you want to receive funds from virtual account payments:

​
Instant Settlement

Funds are immediately transferred to your main balance upon payment receipt. Pros:
  • Immediate access to funds
  • Real-time liquidity
  • No waiting period
Cons:
  • No float period
  • Immediate reconciliation required

​
Scheduled Settlement

Funds are batched and settled at specific intervals (daily, weekly, etc.) Pros:
  • Better cash flow management
  • Reduced transaction fees
  • Easier bulk reconciliation
Cons:
  • Delayed access to funds
  • Working capital tied up

​
Account Naming

Fossapay supports custom account names for better branding: 
{
  "account_name": "ACME Corp - John Doe",
  "business_name": "ACME Corporation"
}
Account names appear on your customer’s bank statement when they transfer money.

​
Virtual Account Metadata

Store custom data with each virtual account for easier tracking: 
{
  "customer_id": "cus_abc123",
  "metadata": {
    "user_id": "12345",
    "subscription_plan": "premium",
    "department": "sales",
    "campaign": "q1-promo"
  }
}

​
Supported Banks

Virtual accounts are currently available for these banks:
  • Wema Bank - Primary provider
  • Sterling Bank - Coming soon
  • Providus Bank - Coming soon
Regardless of the provider bank, customers can transfer from ANY Nigerian bank to your virtual accounts.

​
Limits and Restrictions

FeatureLimit
Accounts per businessUnlimited
Minimum amount₦100
Maximum single transaction₦5,000,000
Daily transaction limit₦50,000,000
Account creation rate100 per minute
Limits may vary based on your business verification level. Contact support for higher limits.

​
Best Practices

Include customer identifiers in account names for easy reconciliation:
"YourBrand - Customer Name"
Always include relevant metadata to track accounts:
{
  "metadata": {
    "customer_id": "internal_id_123",
    "created_by": "user_456"
  }
}
  • Verify webhook signatures
  • Respond with 200 status quickly
  • Process transactions asynchronously
  • Implement idempotency
For invoice payments, set an expiry date:
{
  "expires_at": "2024-12-31T23:59:59Z"
}

​
Common Use Cases

​
Wallet Top-ups

// Create a dedicated account for each user
const account = await fossapay.virtualAccounts.create({
  type: 'dedicated',
  customer_name: user.fullName,
  customer_email: user.email,
  metadata: {
    user_id: user.id,
    purpose: 'wallet_topup'
  }
});

// Show account number to user
// When they transfer, webhook fires and you credit their wallet

​
Invoice Payments

// Create temporary account for invoice
const account = await fossapay.virtualAccounts.create({
  type: 'temporary',
  customer_name: invoice.customerName,
  amount: invoice.amount,
  expires_at: invoice.dueDate,
  metadata: {
    invoice_id: invoice.id
  }
});

​
Subscription Collections

// Create account once, reuse for recurring payments
const account = await fossapay.virtualAccounts.create({
  type: 'dedicated',
  customer_name: subscriber.name,
  metadata: {
    subscription_id: subscription.id,
    plan: 'monthly'
  }
});

​
Next Steps

Create Virtual Account

Learn how to create virtual accounts via API

Collections Guide

Complete guide to accepting payments

Webhooks

Handle payment notifications

Settlements

Understand settlement options