Create permanent virtual account

New to virtual accounts? Read the overview first — it explains the difference between permanent and permanent_collection, which matters before you pick one.

This endpoint creates a multi-use virtual account of one of two types:

permanent — behaves like a wallet. Funds received into it accumulate as a balance you later move out via Withdraw funds or a virtual account transfer.
permanent_collection — a pass-through account. It exists to identify incoming payments, not to hold them.

Both types can accept unlimited incoming payments and never expire on their own.

Endpoint

POST /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.

Request body

string

required

First name to assign to the virtual account holder.

string

required

Last name to assign to the virtual account holder.

string

required

Account type. Accepted values: "permanent" (wallet — holds a balance) or "permanent_collection" (pass-through — see overview).

string

required

The account holder’s Bank Verification Number. Must be exactly 11 digits.

string

required

A unique reference string you generate to identify this account in your system. Must be unique across your account — creating a second account with a reference you’ve already used returns an error.

Response

Returns 201 Created on success.

boolean

true on success.

string

Confirmation message, e.g. "Account generated successfully".

string

The NUBAN account number generated for this virtual account.

string

The name on the account, derived from the firstName and lastName provided.

string

The reference you supplied, echoed back for confirmation.

string

A unique reference generated by Interstellas for this account.

Example response

{
  "status": true,
  "message": "Account generated successfully",
  "data": {
    "accountNumber": "9000081483",
    "accountName": "Tola Wuyi",
    "clientRef": "Bu90037366fcMn",
    "systemRef": "STL|jYcphJZcT73yjv"
  }
}

Code examples

curl -X POST https://sandbox.stellasbank.com/api/v1/clients/business/virtual-accounts \
  -H "x-api-key: stl_c8e286ca55b0123e0b05da047494f585" \
  -H "x-api-secret: stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0" \
  -H "businessId: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "type": "permanent",
    "bvn": "12345678901",
    "reference": "ref_unique_001"
  }'

const res = await fetch(
  "https://sandbox.stellasbank.com/api/v1/clients/business/virtual-accounts",
  {
    method: "POST",
    headers: {
      "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
      "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
      businessId: "YOUR_BUSINESS_ID",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      firstName: "Ada",
      lastName: "Lovelace",
      type: "permanent",
      bvn: "12345678901",
      reference: "ref_unique_001",
    }),
  }
);
const { data } = await res.json();

import requests

res = requests.post(
    "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",
    },
    json={
        "firstName": "Ada",
        "lastName": "Lovelace",
        "type": "permanent",
        "bvn": "12345678901",
        "reference": "ref_unique_001",
    },
)
print(res.json())

Errors

Status	Cause
`400 Bad Request`	`reference`, `firstName`, `lastName`, or `bvn` missing
`400 Bad Request`	`bvn` is not exactly 11 characters
`400 Bad Request`	`type` is anything other than `"permanent"` or `"permanent_collection"`
`400 Bad Request`	`reference` already exists (`"Reference already exists"`)
`400 Bad Request`	`"No payment account for this business"` — set up your business’s own payment account first
`401 Unauthorized`	`businessId` header missing, or credentials invalid

See Errors for the full envelope and error code reference.

Next steps

Withdraw funds

Move a balance out of a permanent account.

List virtual accounts

See every virtual account for your business.

Overview

Members

Business

Virtual accounts

Funds

Bulk transfers

Disputes

Subscriptions

Payouts

Audit logs

Settings

Create permanent virtual account

Endpoint

Headers

Request body

Response

Example response

Code examples

Errors

Next steps

Withdraw funds

List virtual accounts

​Endpoint

​Headers

​Request body

​Response

​Example response

​Code examples

​Errors

​Next steps

Withdraw funds

List virtual accounts

Endpoint

Headers

Request body

Response

Example response

Code examples

Errors

Next steps