Virtual Accounts Overview

Create and manage tenant-scoped virtual accounts

Virtual accounts let you allocate bank-transfer receiving accounts for your customers through the Zentra control plane.

What They Do

A virtual account gives a customer a dedicated account number that maps back to your tenant. When inbound payments are processed, Zentra records the credit and your integration can react through downstream workflows and webhooks.

Typical Use Cases

Customer Deposits

Let customers fund their balances through bank transfers.

Collections

Reconcile transfer-based collections against a dedicated account record.

Merchant Settlement Flows

Allocate receiving accounts per merchant, business, or counterparty.

Operational Routing

Route account creation through provider-aware internal policies instead of hard-coding a single bank.

How It Works

1. Create Account: Call POST /api/v1/virtual-accounts with customer_id and account_name.
2. Provider Selection: Zentra routes the request internally and allocates the account with the selected provider.
3. Share Details: Present the returned account_number, bank_name, and account_name to your customer.
4. Track Inbound Value: Use total_received_minor and transaction_count for reporting.
5. Manage Lifecycle: Retrieve, list, freeze, unfreeze, reserve-assign, or close through the internal service contract; the reviewed public API surface currently exposes create, get, list, and close.

Input Model

The current reviewed create endpoint supports:

• required:
  • customer_id
  • account_name
• optional:
  • provider
  • account_type
  • metadata
  • bvn
  • country
  • currency
  • request_id
  • preferred_bank

bank_code is not a create input on the reviewed endpoint. It is returned after provider allocation.

Account States

Status	Meaning
active	Account can receive payments
frozen	Account is temporarily blocked
closed	Account has been closed
expired	Provider allocation has expired

Available Operations

Create Account

Generate a new virtual account

Get Account

Retrieve account details

List Accounts

List all virtual accounts

Close Account

Close an account

Quick Example

JavaScript

const account = await client.virtualAccounts.create({
  customerId: 'cus_123',
  accountName: 'John Doe Collections'
});

console.log(`Account Number: ${account.accountNumber}`);
console.log(`Bank: ${account.bankName}`);

account = client.virtual_accounts.create(
    customer_id='cus_123',
    account_name='John Doe Collections'
)

print(f"Account Number: {account.account_number}")
print(f"Bank: {account.bank_name}")

$account = $client->virtualAccounts->create([
    'customer_id' => 'cus_123',
    'account_name' => 'John Doe Collections'
]);

echo "Account Number: {$account->account_number}\n";
echo "Bank: {$account->bank_name}";

Integration Notes

Provider Choice Is Internal

If you omit provider, the gateway defaults it to auto and the internal routing layer chooses the provider.

Bank Preference Is Only A Hint

Use preferred_bank only when your provider path supports it. The final bank_code and bank_name come from the provider response.

Money Fields Use Minor Units

total_received_minor is the running inbound amount. Do not expect decimal money fields in the API response.

Metadata Round-Trips

Structured metadata is preserved on create, get, list, and close responses.

Next Steps

Create Virtual Account

Learn how to create accounts

Webhooks

Handle account events

Customers

Manage customer records