Skip to main content
POST
/
api
/
v1
/
virtual-accounts
Create Virtual Account
curl --request POST \
  --url https://api.usezentra.com/api/v1/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "account_name": "<string>",
  "provider": "<string>",
  "account_type": "<string>",
  "metadata": {},
  "bvn": "<string>",
  "country": "<string>",
  "currency": "<string>",
  "request_id": "<string>",
  "preferred_bank": "<string>"
}
'
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "customer_id is required",
    "details": null
  },
  "meta": {
    "path": "/api/v1/virtual-accounts",
    "method": "POST"
  }
}

​
Create Virtual Account

Create a dedicated virtual account for a customer.

​
Endpoint

POST /api/v1/virtual-accounts

​
Request Body

​
customer_id
string
required
ID of the customer this account belongs to.
​
account_name
string
required
Name to display on the account.
​
provider
string
Optional provider override. If omitted, the gateway defaults this to auto and internal routing selects the provider.
​
account_type
string
Optional account type. Supported values depend on your tenant configuration. Common values are standard and dedicated.
​
metadata
object
Optional metadata stored with the account.
​
bvn
string
Optional BVN when required by your provider or compliance flow.
​
country
string
Optional ISO country code used for provider routing.
​
currency
string
Optional currency code used for provider routing.
​
request_id
string
Optional request correlation ID.
​
preferred_bank
string
Optional preferred bank hint for providers that support bank selection.

​
Response Fields

​
id
string
Unique identifier for the virtual account.
​
tenant_id
string
Tenant that owns the account.
​
customer_id
string
Customer assigned to the account.
​
account_number
string
Account number returned by the underlying provider.
​
account_name
string
Name on the account.
​
bank_code
string
Provider bank code or slug.
​
bank_name
string
Human-readable bank name.
​
provider
string
Provider selected for the account.
​
status
string
Current account status. Typical values are active, frozen, closed, or expired.
​
account_type
string
Account type stored by the service.
​
total_received_minor
number
Total inbound value recorded on the account, in minor units.
​
transaction_count
number
Number of inbound credits recorded on the account.
​
metadata
object | null
Account metadata.
​
expires_at
string | null
Provider expiry time when the allocated account is time-bound.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last-update timestamp.

​
Example Request

const account = await client.virtualAccounts.create({
  customerId: 'cus_1234567890',
  accountName: 'John Doe Collections',
  preferredBank: 'wema-bank',
  metadata: {
    purpose: 'collections',
    tier: 'premium'
  }
});

console.log(account.accountNumber);

​
Example Response

{
  "data": {
    "id": "va_abc123xyz",
    "tenant_id": "tenant_123",
    "customer_id": "cus_1234567890",
    "account_number": "0123456789",
    "account_name": "John Doe Collections",
    "bank_code": "wema-bank",
    "bank_name": "Wema Bank",
    "provider": "paystack_dva",
    "status": "active",
    "account_type": "standard",
    "total_received_minor": 0,
    "transaction_count": 0,
    "metadata": {
      "purpose": "collections",
      "tier": "premium"
    },
    "expires_at": null,
    "created_at": "2026-03-07T10:30:00Z",
    "updated_at": "2026-03-07T10:30:00Z"
  },
  "meta": {
    "timestamp": "2026-03-07T10:30:00Z",
    "requestId": "req_123"
  }
}

​
Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "customer_id is required",
    "details": null
  },
  "meta": {
    "path": "/api/v1/virtual-accounts",
    "method": "POST"
  }
}

​
Notes

bank_code is an output field. The BaaS create endpoint does not require a bank code; use preferred_bank only when you need to bias provider selection.
Amounts are always returned in integer minor units. For virtual accounts, the running inbound total is total_received_minor.

​
Next Steps

Get Account

Retrieve account details

List Accounts

View all accounts

Handle Webhooks

Process account credits

Close Account

Close an account