Virtual accounts

Create (or return) my standing virtual account

Issues one durable collection account for the requested currency, owned by your master account — or by the sub-account named in Zuba-Account-Id, whose deposits then settle into that sub-account’s balance. Idempotent per owner and currency: if a live account already exists it is returned with 201 → 200. Some accounts are issued asynchronously and return status: pending; subscribe to the virtual_account.active / virtual_account.failed webhook events for the outcome. On virtual_account.active, fetch the issued details with GET /v1/virtual-accounts (polling that endpoint works too, but the webhook is the intended completion signal); a refused account is absent from that list. pending is a normal state, not an error: activation is validated out of band, can take far longer than a request cycle, and no account number exists until it completes. Requires the owner’s application to be approved.

POST

virtual-accounts

curl --request POST \
  --url https://api.example.com/v1/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "EUR",
  "country": "SN"
}
'

import requests

url = "https://api.example.com/v1/virtual-accounts"

payload = {
    "currency": "EUR",
    "country": "SN"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({currency: 'EUR', country: 'SN'})
};

fetch('https://api.example.com/v1/virtual-accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/virtual-accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'currency' => 'EUR',
    'country' => 'SN'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/virtual-accounts"

	payload := strings.NewReader("{\n  \"currency\": \"EUR\",\n  \"country\": \"SN\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/virtual-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"currency\": \"EUR\",\n  \"country\": \"SN\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/virtual-accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"currency\": \"EUR\",\n  \"country\": \"SN\"\n}"

response = http.request(request)
puts response.read_body

{
  "accountName": "Zuba John Doe",
  "accountNumber": "8012345678",
  "accountType": "fixed_va",
  "bankName": "Wema Bank",
  "clientId": "456e7890-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "currency": "NGN",
  "enabled": true,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "updatedAt": "2023-11-07T05:31:56Z",
  "accountId": {},
  "bankAddress": {},
  "country": {},
  "displayName": {},
  "iban": "GB50IKMA24711059277481",
  "providerStatus": {},
  "provisioningStatus": {},
  "routingNumber": "138344690",
  "sortCode": "247110",
  "sweepable": true,
  "updatedBy": {}
}

{
  "accountName": "Zuba John Doe",
  "accountNumber": "8012345678",
  "accountType": "fixed_va",
  "bankName": "Wema Bank",
  "clientId": "456e7890-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "currency": "NGN",
  "enabled": true,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "updatedAt": "2023-11-07T05:31:56Z",
  "accountId": {},
  "bankAddress": {},
  "country": {},
  "displayName": {},
  "iban": "GB50IKMA24711059277481",
  "providerStatus": {},
  "provisioningStatus": {},
  "routingNumber": "138344690",
  "sortCode": "247110",
  "sweepable": true,
  "updatedBy": {}
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Headers

Zuba-Account-Id

string<uuid>

Optional. Names an owned sub-account (UUID) to act on. Omit to act at the master (tenant) level. Naming an account this key does not own returns 403 not_account_owner.

Body

application/json

currency

string

required

ISO-4217 currency of the standing account. One live account per owner and currency; repeating a request returns the existing account.

Example:

"EUR"

country

string

ISO 3166-1 alpha-2 country the money is collected in. Required for currencies collected in more than one country (e.g. XOF); ignored otherwise.

Example:

"SN"

Response

A live account already existed for this owner + currency

accountName

object | null

required

Account name (format: "Zuba {Merchant Name}")

Example:

"Zuba John Doe"

accountNumber

object | null

required

Virtual account number. For a GBP SCAN account this is the UK domestic (Faster Payments) account number that pairs with sortCode, not the default identifier; for EUR it is the IBAN.

Example:

"8012345678"

accountType

string

required

Account type

Example:

"fixed_va"

bankName

object | null

required

Bank name where the virtual account is held

Example:

"Wema Bank"

clientId

string<uuid>

required

Client ID this virtual account belongs to

Example:

"456e7890-e89b-12d3-a456-426614174000"

createdAt

string<date-time>

required

Creation timestamp

Example:

"2024-01-15T10:30:00.000Z"

currency

string

required

Currency of the virtual account

Example:

"NGN"

enabled

boolean

required

Routing eligibility. False for failed or incomplete provider workflows.

string<uuid>

required

Unique identifier for the virtual account

Example:

"123e4567-e89b-12d3-a456-426614174000"

status

enum<string>

required

Current status of the virtual account

Available options:

pending,

active,

inactive

Example:

"active"

updatedAt

string<date-time>

required

Last update timestamp

accountId

object | null

Owning sub-account; null for the client master account.

bankAddress

object | null

Institution or branch address supplied by the provider.

country

object | null

ISO 3166-1 alpha-2 country of the receiving account.

displayName

object | null

The name submitted to the provider as the account holder when the account was opened. On accounts opened in the owner's own name this is the owner's KYB-approved legal name; on accounts opened before that was enforced it may be an internal label or the client id, and is not a verified legal name. Null on rails that submit no holder name, where accountName is the only name reported.

iban

object | null

IBAN for the account — the GB IBAN for a GBP SCAN account (whose accountNumber is the SCAN number), or the primary IBAN for EUR. Null when the account exposes no IBAN.

Example:

"GB50IKMA24711059277481"

providerStatus

object | null

Raw provider account status when supplied.

provisioningStatus

object | null

Asynchronous provisioning workflow status when supplied.

routingNumber

object | null

Routing number for USD wire accounts (US ABA). Null for accounts without one (e.g. EUR/GBP).

Example:

"138344690"

sortCode

object | null

Sort code for GBP SCAN accounts (UK Faster Payments). Null for accounts without one (e.g. EUR/IBAN accounts).

Example:

"247110"

sweepable

boolean | null

Per-account treasury-sweep override (admin view only). true/false override the client policy default; null inherits it. Null for merchant callers.

updatedBy

object | null

Create (or return) my standing virtual account

curl --request POST \
  --url https://api.example.com/v1/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "EUR",
  "country": "SN"
}
'

import requests

url = "https://api.example.com/v1/virtual-accounts"

payload = {
    "currency": "EUR",
    "country": "SN"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({currency: 'EUR', country: 'SN'})
};

fetch('https://api.example.com/v1/virtual-accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/virtual-accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'currency' => 'EUR',
    'country' => 'SN'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/virtual-accounts"

	payload := strings.NewReader("{\n  \"currency\": \"EUR\",\n  \"country\": \"SN\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/virtual-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"currency\": \"EUR\",\n  \"country\": \"SN\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/virtual-accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"currency\": \"EUR\",\n  \"country\": \"SN\"\n}"

response = http.request(request)
puts response.read_body

{
  "accountName": "Zuba John Doe",
  "accountNumber": "8012345678",
  "accountType": "fixed_va",
  "bankName": "Wema Bank",
  "clientId": "456e7890-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "currency": "NGN",
  "enabled": true,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "updatedAt": "2023-11-07T05:31:56Z",
  "accountId": {},
  "bankAddress": {},
  "country": {},
  "displayName": {},
  "iban": "GB50IKMA24711059277481",
  "providerStatus": {},
  "provisioningStatus": {},
  "routingNumber": "138344690",
  "sortCode": "247110",
  "sweepable": true,
  "updatedBy": {}
}

{
  "accountName": "Zuba John Doe",
  "accountNumber": "8012345678",
  "accountType": "fixed_va",
  "bankName": "Wema Bank",
  "clientId": "456e7890-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "currency": "NGN",
  "enabled": true,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "updatedAt": "2023-11-07T05:31:56Z",
  "accountId": {},
  "bankAddress": {},
  "country": {},
  "displayName": {},
  "iban": "GB50IKMA24711059277481",
  "providerStatus": {},
  "provisioningStatus": {},
  "routingNumber": "138344690",
  "sortCode": "247110",
  "sweepable": true,
  "updatedBy": {}
}