List Virtual Accounts
curl --request GET \
--url https://api.usezentra.com/api/v1/virtual-accounts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.usezentra.com/api/v1/virtual-accounts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usezentra.com/api/v1/virtual-accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usezentra.com/api/v1/virtual-accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usezentra.com/api/v1/virtual-accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.usezentra.com/api/v1/virtual-accounts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usezentra.com/api/v1/virtual-accounts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyList Virtual Accounts
GET /api/v1/virtual-accounts - List virtual accounts for the authenticated tenant
GET
/
api
/
v1
/
virtual-accounts
List Virtual Accounts
curl --request GET \
--url https://api.usezentra.com/api/v1/virtual-accounts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.usezentra.com/api/v1/virtual-accounts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usezentra.com/api/v1/virtual-accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usezentra.com/api/v1/virtual-accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usezentra.com/api/v1/virtual-accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.usezentra.com/api/v1/virtual-accounts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usezentra.com/api/v1/virtual-accounts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyRetrieve a paginated list of virtual accounts for the authenticated tenant.
Endpoint
GET /api/v1/virtual-accounts
Query Parameters
string
Filter by customer ID.
string
Filter by account status.
string
Filter by account type.
string
Filter by provider bank code or slug.
number
default:"1"
Page number. The gateway converts this into
offset internally.number
default:"20"
Results per page. Maximum
100.number
Explicit record offset. If both
page and offset are supplied, offset wins.string
Sort field. Supported values:
created_at, -created_at, account_number, -account_number, total_received_minor, -total_received_minor. The legacy aliases total_credits and -total_credits are also accepted.Response
List responses return adata object containing items and pagination.
Example Request
const accounts = await client.virtualAccounts.list({
customerId: 'cus_123',
status: 'active',
page: 2,
limit: 25,
sort: '-created_at'
});
console.log(`Total: ${accounts.data.pagination.total}`);
accounts.data.items.forEach(account => {
console.log(`${account.accountNumber} - ${account.bankName}`);
});
accounts = client.virtual_accounts.list(
customer_id='cus_123',
status='active',
page=2,
limit=25,
sort='-created_at'
)
print(f"Total: {accounts.data.pagination.total}")
for account in accounts.data.items:
print(f"{account.account_number} - {account.bank_name}")
$accounts = $client->virtualAccounts->list([
'customer_id' => 'cus_123',
'status' => 'active',
'page' => 2,
'limit' => 25,
'sort' => '-created_at'
]);
echo "Total: {$accounts->data->pagination->total}\n";
foreach ($accounts->data->items as $account) {
echo "{$account->account_number} - {$account->bank_name}\n";
}
curl "https://api.usezentra.com/api/v1/virtual-accounts?customer_id=cus_123&status=active&page=2&limit=25&sort=-created_at" \
-H "Authorization: Bearer YOUR_SECRET_KEY"
Example Response
{
"data": {
"items": [
{
"id": "va_abc123xyz",
"tenant_id": "tenant_123",
"customer_id": "cus_1234567890",
"account_number": "0123456789",
"account_name": "John Doe",
"bank_code": "wema-bank",
"bank_name": "Wema Bank",
"provider": "paystack_dva",
"status": "active",
"account_type": "standard",
"total_received_minor": 500000,
"transaction_count": 5,
"metadata": {
"purpose": "collections"
},
"expires_at": null,
"created_at": "2026-03-07T10:30:00Z",
"updated_at": "2026-03-07T15:45:00Z"
}
],
"pagination": {
"page": 2,
"limit": 25,
"offset": 25,
"total": 26,
"pages": 2,
"has_more": true
}
},
"meta": {
"timestamp": "2026-03-07T15:45:00Z",
"requestId": "req_123"
}
}
Sorting
# Newest first (default)
GET /api/v1/virtual-accounts?sort=-created_at
# Oldest first
GET /api/v1/virtual-accounts?sort=created_at
# Highest inbound value first
GET /api/v1/virtual-accounts?sort=-total_received_minor
# Legacy alias, still accepted
GET /api/v1/virtual-accounts?sort=-total_credits
# By account number
GET /api/v1/virtual-accounts?sort=account_number
Filtering Examples
const active = await client.virtualAccounts.list({ status: 'active' });
const customerAccounts = await client.virtualAccounts.list({ customerId: 'cus_123' });
const wemaAccounts = await client.virtualAccounts.list({ bankCode: 'wema-bank' });
const filtered = await client.virtualAccounts.list({
customerId: 'cus_123',
status: 'active',
bankCode: 'wema-bank',
accountType: 'standard'
});
active = client.virtual_accounts.list(status='active')
customer_accounts = client.virtual_accounts.list(customer_id='cus_123')
wema_accounts = client.virtual_accounts.list(bank_code='wema-bank')
filtered = client.virtual_accounts.list(
customer_id='cus_123',
status='active',
bank_code='wema-bank',
account_type='standard'
)
$active = $client->virtualAccounts->list(['status' => 'active']);
$customerAccounts = $client->virtualAccounts->list(['customer_id' => 'cus_123']);
$wemaAccounts = $client->virtualAccounts->list(['bank_code' => 'wema-bank']);
$filtered = $client->virtualAccounts->list([
'customer_id' => 'cus_123',
'status' => 'active',
'bank_code' => 'wema-bank',
'account_type' => 'standard'
]);
Notes
Legacy wrapper payloads like
filters or params are rejected on this reviewed endpoint. Send query parameters directly.Next Steps
Get Account
Retrieve a single account
Create Account
Generate a new virtual account
Close Account
Close an account
Was this page helpful?