Create Virtual Account

A Virtual Account is a system-generated account that allows you to:

• Receive funds programmatically
• Hold balances per customer or use-case
• Enable wallet-like experiences
• Support deposits, deductions, and internal transfers

Virtual Accounts are ideal for:

• Customer wallets
• Escrow accounts
• Marketplace balances
• Prepaid and stored-value systems

When to Use Virtual Accounts

Use Virtual Accounts when you need:

• A unique account per customer or merchant
• Separation of funds by purpose
• Programmatic credit and debit operations
• Transaction history and balance tracking

Endpoint

POST /v2/virtual-accounts
Host: api.chapa.co

Authentication

Headers

Request Body

Required Fields

Optional Fields

Example Request

POST https://api.chapa.co/v2/virtual-accounts
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

{
  "account_name": "John Doe Wallet",
  "currency": "ETB",
  "merchant_reference": "VA_001",
  "meta": {
    "customer_id": "CUST_12345"
  }
}

Example Response

{
  "status": "success",
  "message": "Virtual account created successfully",
  "data": {
    "virtual_account_id": "VA_ABC123456",
    "account_name": "John Doe Wallet",
    "currency": "ETB",
    "balance": 0,
    "created_at": "2025-11-07T10:00:00Z"
  }
}

Response Fields

Virtual Account Object

Key Notes

• Virtual accounts start with a zero balance
• Funds must be deposited before they can be used
• Currency is fixed and cannot be changed later
• Each virtual account is isolated from others

Best Practices

• Use merchant_reference to map accounts internally
• Create one virtual account per customer or use-case
• Store virtual_account_id securely
• Avoid recreating accounts on retries (use idempotency)

Common Errors

Next Steps

• Get Virtual Account - Retrieve account details
• Deposit to Virtual Account - Add funds
• Deduct from Virtual Account - Withdraw funds