Virtual accounts

What this owner still needs before an account can be issued

Answers, without issuing anything, whether a virtual account could be created right now for the request owner in the given currency — and when it could not, exactly what is outstanding and which call supplies it. Collect the answers from your customer before requesting the account, rather than discovering them from a failed request.

Branch on ready; read code on each requirement, not its prose. A null resolution means no API call sets that requirement: it is either a fact assessed at review or a state of the owner or the workspace. Its description says what clears it.

GET

virtual-accounts

requirements

What this owner still needs before an account can be issued

curl --request GET \
  --url https://api.example.com/v1/virtual-accounts/requirements \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/virtual-accounts/requirements', 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/requirements",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "country": "SN",
  "currency": "USD",
  "ready": false,
  "requirements": [
    {
      "code": "business.industry_code",
      "description": "The 6-digit NAICS code describing what the business does.",
      "resolution": {
        "field": "industryCode",
        "method": "POST",
        "path": "/v2/applications/6f1c0f5e-6f0e-4a2f-9c1e-9d0f5a2b3c4d/enrich"
      },
      "scope": "business"
    }
  ],
  "status": "action_required"
}

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.

Query Parameters

currency

string

required

ISO-4217 currency the account would be issued in. Requirements differ per currency, so this is required.

Example:

"USD"

country

string

ISO 3166-1 alpha-2 country the money would be collected in. Supply it for currencies collected in more than one country, exactly as the create call would; omitting it where it is needed is itself reported as a requirement.

Example:

"SN"

Response

Outstanding requirements for the request owner

country

string | null

required

The country this answer was computed for, or null when none was given.

Example:

"SN"

currency

string

required

Example:

"USD"

ready

boolean

required

True when a create call would succeed now. The single field to branch on; status and requirements say why not.

Example:

false

requirements

object[]

required

Empty when nothing is outstanding.

Show child attributes

status

enum<string>

required

already_exists — an account is already issued for this owner and currency. action_required — the requirements below are outstanding. unavailable — this currency is not offered to this owner, and no field they supply will change that.

Available options:

ready,

already_exists,

action_required,

unavailable

Example:

"action_required"

What this owner still needs before an account can be issued

curl --request GET \
  --url https://api.example.com/v1/virtual-accounts/requirements \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/virtual-accounts/requirements', 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/requirements",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "country": "SN",
  "currency": "USD",
  "ready": false,
  "requirements": [
    {
      "code": "business.industry_code",
      "description": "The 6-digit NAICS code describing what the business does.",
      "resolution": {
        "field": "industryCode",
        "method": "POST",
        "path": "/v2/applications/6f1c0f5e-6f0e-4a2f-9c1e-9d0f5a2b3c4d/enrich"
      },
      "scope": "business"
    }
  ],
  "status": "action_required"
}