Skip to main content
Returns every virtual account your business has created — permanent, permanent_collection, and single-use accounts together.

​
Endpoint

GET /clients/business/virtual-accounts

​
Headers

​
x-api-key
string
required
Your public API key.
​
x-api-secret
string
required
Your API secret. Use a stl_test_... value in sandbox, stl_live_... in production.
​
businessId
string
required
Your business ID.

​
Query parameters

​
page
integer
Page number. Defaults to 1.
​
limit
integer
Records per page. Defaults to 10.
​
clientRef
string
Filter to the account created with this reference (or refCode, for single-use accounts).
​
accountNumber
string
Filter to a specific NUBAN account number.
​
dateFrom
string
ISO 8601 date — only include accounts created on or after this date.
​
dateTo
string
ISO 8601 date — only include accounts created on or before this date.
See Pagination for full usage — this endpoint uses Shape B.

​
Response

​
status
boolean
true on success.
​
message
string
Human-readable outcome.
​
data
array
Array of virtual account objects.
​
data[].id
string
Unique ID for this virtual account. Use this with Get virtual account by ID.
​
data[].clientRef
string
The reference (or refCode) supplied when this account was created.
​
data[].systemRef
string
The unique reference Interstellas generated for this account.
​
data[].name
string
The name on the account.
​
data[].accountNumber
string
The NUBAN account number.
​
data[].bvn
string
The BVN associated with this account, if one was set at creation.
​
data[].businessId
string
The business this account belongs to.
​
data[].dateCreated
string
ISO 8601 timestamp of when the account was created.
​
pagination.page
integer
The current page number.
​
pagination.limit
integer
The page size used for this response.
​
pagination.total
integer
Total number of accounts matching the current query, across all pages.
​
pagination.totalPages
integer
The final page number, derived from total ÷ limit.

​
Code examples

curl -X GET "https://sandbox.stellasbank.com/api/v1/clients/business/virtual-accounts?page=1&limit=10" \
  -H "x-api-key: stl_c8e286ca55b0123e0b05da047494f585" \
  -H "x-api-secret: stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0" \
  -H "businessId: YOUR_BUSINESS_ID"

const res = await fetch(
  "https://sandbox.stellasbank.com/api/v1/clients/business/virtual-accounts?page=1&limit=10",
  {
    headers: {
      "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
      "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
      businessId: "YOUR_BUSINESS_ID",
    },
  }
);
const { data, pagination } = await res.json();

import requests

res = requests.get(
    "https://sandbox.stellasbank.com/api/v1/clients/business/virtual-accounts",
    headers={
        "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
        "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
        "businessId": "YOUR_BUSINESS_ID",
    },
    params={"page": 1, "limit": 10},
)
print(res.json())

​
Example response

{
  "status": true,
  "message": "Successful",
  "data": [
    {
      "id": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
      "clientRef": "ref_unique_001",
      "systemRef": "STL|jYcphJZcT73yjv",
      "name": "Ada Lovelace",
      "accountNumber": "9000081483",
      "bvn": "12345678901",
      "businessId": "biz_xyz789",
      "dateCreated": "2024-06-09T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

​
Errors

StatusCause
400 Bad RequestbusinessId header missing, or not a valid UUID
401 UnauthorizedCredentials missing or invalid
See Errors for the full envelope and error code reference.