Skip to main content
All virtual account webhooks are sent to your collection_url.

​
Parameter overview

ParameterDescription
eventEvent type identifier (e.g., “virtual_account.ready”)
virtual_account_idUnique ID of the virtual account
customer_idYour customer’s ID (from customer creation)
wallet_idThe wallet ID this account is linked to
currencyCurrency code (NGN, USD, GBP, EUR)
statusCurrent status (PENDING, SUCCESSFUL, REJECTED)
account_numberBank account number (only in ready event)
account_nameAccount holder name (only in ready event)
bank_nameBank institution name (only in ready event)
bank_codeBank code (NGN only)
routing_numberRouting/ABA number (USD only)
ibanIBAN number (GBP/EUR only)
sort_codeUK sort code (GBP only)
bank_addressBank address (USD only)
rejection_reasonTechnical reason for rejection (rejected event only)
user_reasonUser-friendly rejection message (rejected event only)
developer_reasonDeveloper-specific rejection code (rejected event only)

​
Event types

​
virtual_account.created

Account creation initiated but not yet ready. 
{
  "event": "virtual_account.created",
  "virtual_account_id": "vba_pending123",
  "customer_id": "cust_abc456",
  "wallet_id": "wallet_xyz789",
  "currency": "NGN",
  "status": "PENDING"
}

​
virtual_account.ready

Account fully created and ready to receive funds. 
{
  "event": "virtual_account.ready",
  "virtual_account_id": "vba_ngn_success123",
  "customer_id": "cust_abc456",
  "wallet_id": "wallet_xyz789",
  "currency": "NGN",
  "status": "SUCCESSFUL",
  "account_number": "1234567890",
  "account_name": "Customer Business Name",
  "bank_name": "Wema Bank",
  "bank_code": "035",
  "routing_number": null,
  "iban": null,
  "sort_code": null,
  "bank_address": null
}

​
virtual_account.rejected

Verification failed. 
{
  "event": "virtual_account.rejected",
  "virtual_account_id": "vba_usd_rejected999",
  "customer_id": "cust_rejected123",
  "wallet_id": "wallet_usd999",
  "currency": "USD",
  "status": "REJECTED",
  "rejection_reason": "Customer verification failed: insufficient documentation provided",
  "user_reason": "Your application could not be processed",
  "developer_reason": "CUSTOMER_VERIFICATION_FAILED"
}