List virtual accounts

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

Endpoint

GET /clients/business/virtual-accounts

Headers

string

required

Your public API key.

string

required

Your API secret. Use a stl_test_... value in sandbox, stl_live_... in production.

string

required

Your business ID.

Query parameters

integer

Page number. Defaults to 1.

integer

Records per page. Defaults to 10.

string

Filter to the account created with this reference (or refCode, for single-use accounts).

string

Filter to a specific NUBAN account number.

string

ISO 8601 date — only include accounts created on or after this date.

string

ISO 8601 date — only include accounts created on or before this date.

See Pagination for full usage — this endpoint uses Shape B.

Response

boolean

true on success.

string

Human-readable outcome.

array

Array of virtual account objects.

string

Unique ID for this virtual account. Use this with Get virtual account by ID.

string

The reference (or refCode) supplied when this account was created.

string

The unique reference Interstellas generated for this account.

string

The name on the account.

string

The NUBAN account number.

string

The BVN associated with this account, if one was set at creation.

string

The business this account belongs to.

string

ISO 8601 timestamp of when the account was created.

integer

The current page number.

integer

The page size used for this response.

integer

Total number of accounts matching the current query, across all pages.

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

Status	Cause
`400 Bad Request`	`businessId` header missing, or not a valid UUID
`401 Unauthorized`	Credentials missing or invalid

See Errors for the full envelope and error code reference.

Overview

Members

Business

Virtual accounts

Funds

Bulk transfers

Disputes

Subscriptions

Payouts

Audit logs

Settings

Endpoint

Headers

Query parameters

Response

Code examples

Example response

Errors

​Endpoint

​Headers

​Query parameters

​Response

​Code examples

​Example response

​Errors

Endpoint

Headers

Query parameters

Response

Code examples

Example response

Errors