Virtual accounts overview

A virtual account is a dedicated NUBAN account number you generate for a customer or a transaction, so incoming payments arrive already identified — no manual reconciliation. Interstellas supports three account types, and picking the right one matters: it determines whether the account behaves like a wallet you can hold a balance in, or a pass-through that just routes money to your business’s own pool account.

​

The three account types

​

permanent

A permanent virtual account behaves like a wallet: it can hold a running balance across any number of incoming payments. Funds received into it stay on the account until you explicitly move them — using Withdraw funds with the virtual account’s accountNumber as payerAccountNumber, or a virtual account transfer. Use this when you want a persistent, individually-addressable balance — for example, one account per customer that accumulates their deposits over time.

​

permanent_collection

A permanent_collection virtual account is also multi-use and long-lived, but it’s a pass-through: it’s not meant to be a place funds sit. It exists purely to identify the payer/purpose of a payment as it moves into your business’s own pool account. Use this when you want a persistent, individually-addressable account number — for reconciliation purposes, say — but don’t need a per-account balance; you just want everything ultimately settling in your one business account.

​

Single-use

A single-use virtual account is disposable: created for one expected payment, tied to a specific amount and, optionally, a time window, then done. Like permanent_collection, it’s a proxy — it exists to collect one specific payment and identify it, not to hold a balance. See amount and duration matching below for how Interstellas decides whether an incoming payment on one of these accounts is accepted.

​

Choosing a type

​

Amount and duration matching

Single-use accounts are always constrained to an exact amount. They can optionally also be constrained to a duration window, in minutes, counted from creation — see Create single-use virtual account for the exact request shape.

• Amount (always enforced): the incoming payment must exactly match the amount you set. Any difference — paying less or more — causes the transfer to automatically fail; it isn’t credited as a completed collection.
• Duration (optional): if you set one, a payment received after duration minutes have elapsed causes the transfer to automatically fail, even if the amount is exact. If you don’t set a duration, the account never expires on its own and only the amount match applies.

Design your integration around this: a payment on a single-use account either completes because it matched exactly (amount, and time window if set), or it fails outright.

​

Required identity information

All permanent account types (permanent and permanent_collection) require a bvn (Bank Verification Number, 11 digits) for the account holder, in addition to firstName/lastName. Single-use accounts don’t take a bvn from you directly — outside production, Interstellas generates a placeholder automatically; in production, it uses your business’s own BVN on file.

​

Naming and casing

Endpoints in this section are inconsistent about a couple of field names inherited from how each account type was built — for example, the single-use response uses clientRef/systemRef/expirationTime, while other parts of the API use slightly different names for conceptually similar fields. Rely on the field names documented on each endpoint’s own reference page rather than assuming they generalize across account types.