Skip to main content
A virtual account is a bank account number that belongs to one of your customers. Money paid into it lands in your Spotflow balance, and you always know who sent it, because the account number itself identifies them. This guide creates one, reads it back, checks its balance, and deactivates it.

​
What you’ll need

  • Your secret key. Every call in this guide authenticates with it.
  • Nothing else. You do not need an existing account — Spotflow attaches the new sub-account to the main account for the currency you pick.
All calls go to the accounts service:
Virtual accounts live on /accounts/api/v1, not /gateway/api/v1. Calling the gateway path returns 404 No static resource.

​
The shape of the flow

1

Create the account

One call. You get back an account id and a ready-to-use account number.
2

Read it back

Confirm the details, or fetch a summary with its running balance.
3

Check the balance

See what the customer has paid in.
4

Deactivate it

Close the account when the customer leaves.

​
Step 1: Create the account

* You must send either currency or parentAccountId. Sending neither returns 400 currency_required.
Two things to take from this:
  • The account number already exists. accountDetails.accountNumber is live the moment the account is created. There is no second call to provision it. Give 0313471844198 at Jollof Bank to your customer and they can pay in.
  • id is what every later call uses, not the account number. Keep it.
In test mode the provider is MOCK and the bank is Jollof Bank. In live mode these are a real provider and a real bank.

​
Step 2: Read the account back

This returns the same body as the create call. For an operational view, ask for the summary instead:
The summary drops accountDetails but adds currentBalance, totalTransactionVolume (a count) and totalTransactionValue (a sum). You can also list just the account numbers attached to the account:

​
Step 3: Check the balance

The summary’s currentBalance is convenient, but the balance endpoint is the one to poll, and it separates total from available:
balance is everything in the account. availableBalance is what you can actually move — money still settling is in balance but not in availableBalance. Pay out against availableBalance, never balance. To see every account at once, call /balances with no id:
If the account has its own children, /balances/accounts/{id}/sub-balances lists them. For a plain virtual account it returns [].

​
Step 4: Deactivate the account

When the customer leaves, close their account number so nothing more can be paid in.
Despite the DELETE verb, nothing is deleted. status becomes inactive, the account number stays on the record, and GET /accounts/{id} keeps returning it. Treat this as “close”, not “erase” — and filter on status in your own UI.

​
When things go wrong

​
What to do next