Virtual Accounts (FBO)

Virtual Accounts are sub-ledgered balances with unique account identifiers, sitting under a bank account you hold with Augustus. They give you the infrastructure to implement per-customer accounts on your platform, with automated reconciliation and the ability to send and receive payments in your customers’ names. The primary use case is FBO with Virtual Accounts: you open a client-funds account with Augustus For Benefit Of (FBO) your customers, then provision a Virtual Account inside it for each of your end-users. This guide explains how that works and how to integrate it.

FBO with Virtual Accounts

You open a single FBO account at Augustus in your name, for the benefit of your customers. Under the FBO Program, you create one Virtual Account per end-user. Each Virtual Account has:

A unique 12-digit US account number reachable over ACH, Fedwire, and SWIFT.
Its own sub-ledger and balance.
The end-user’s name for sending and receiving payments — Collection-on-Behalf-of (CoBo) and Payment-on-Behalf-of (PoBo).

This gives you per-user accounting and named payments without needing a separate bank account for every customer. Funds remain in your single FBO account; sub-ledgering and naming sit on top.

Two primitives

Account Program. The Account Program that holds your FBO arrangement — in your name, for the benefit of your customers. It defines the capabilities of the accounts inside it and the onboarding policy for their holders. One currency per Program; a setup needing more than one currency uses multiple Programs. Virtual Account. A sub-ledgered balance under your Account Program with its own 12-digit US account number. Created by you via API once the Account Holder has been registered. Used to receive funds in and send funds out in the name of a single end-user.

Status model

Accounts use the four-state model below. Account Programs use a narrower one: active and frozen. Closed programs are not returned by the API.

Status	Behavior
`pending`	Newly opened, not yet activated. Augustus typically activates within minutes. Some accounts require additional information (e.g. enhanced due diligence) before activation.
`active`	Normal. Pay-ins and payouts allowed.
`frozen`	No pay-ins or payouts. Reversible — call POST `/v1/accounts/{id}/unfreeze` to return to `active`.
`closed`	Terminal. The account must be `frozen` first, then closed. Cannot be reopened — open a new Virtual Account if the holder needs an account again.

Cascade rules:

Freezing a Program freezes every account inside it.
Closing a Program requires every account inside it to already be empty or closed.
Account-level status changes never propagate up to the Program.

Beneficiary data: what you provide for each Account Holder

To open a Virtual Account, first register the Account Holder with the beneficiary data for the end-user. Required CIP fields differ by holder type.

natural_person
business

legal_name
residential_address
date_of_birth
identification — ssn or itin for US persons, id (generic government-issued ID) for non-US persons
country_of_citizenship

legal_business_name and doing_business_as
registered_address and physical_address
registration_number — ein or ssn
state_of_incorporation, year_of_incorporation, country_of_incorporation
beneficial_owners — at least one, each with the same fields as a natural person
control_person — the individual with primary responsibility for controlling, managing, or directing the business, with the same fields as a natural person plus their title (e.g. CEO, President)

holder_type accepts natural_person or business. individual is not a valid value.

Open at most one Virtual Account per entity under each Account Program.

Money in: receiving funds

Each Virtual Account has its own routable account number, so funds arriving over US rails settle directly into the right Virtual Account without you doing any routing.

Rail	Speed	Use case
ACH	Same-day settlement windows	Low-cost retail flows
Fedwire	Minutes during operating hours	High-value or time-critical payments
SWIFT (USD)	Depends on the sender’s correspondent chain	International USD inbound to your end-users

When a credit arrives, Augustus matches the destination account number to a Virtual Account, performs sanctions and AML screening, and credits the Virtual Account’s balance. You receive a webhook on the Virtual Account. If a credit can’t be matched (wrong account number, sanctions hit, frozen account), Augustus returns it via the originating rail and notifies you with the reason.

Money out: sending funds

You initiate payouts from a Virtual Account — the source account is the Virtual Account. The end-user’s name appears as the originator on the rail, known as Payment-on-Behalf-of (PoBo). The Virtual Account holder’s name appears to the receiving bank and beneficiary. Funds are debited from the Virtual Account atomically at payout initiation. Payouts use the existing Payouts API: pass the Virtual Account’s ID as account_id; the request and response shapes are otherwise unchanged.

Integration

The endpoints below show the shape of the API and the key calls you’ll make to integrate Virtual Accounts. The full reference, including all status-change endpoints, lives in the API reference. All Account, Account Holder, and Account Program endpoints sit under the /v1/accounts/*, /v1/account_holders/*, and /v1/account_programs/* namespaces. They follow the same auth, error, and pagination conventions as the rest of the 2026-05-01 API.

Sandbox. All Virtual Account flows are available in sandbox mode with simulated rail movements. See Sandbox Mode.

Open a Virtual Account

Opening a Virtual Account is two calls: register the Account Holder with the beneficiary data, then create the account for that holder under your Program.

2026-05-01

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()

// 1. Register the account holder
const holder = await client.accountHolders.create({
  account_program_id: '550e8400-e29b-41d4-a716-446655440002',
  holder_type: 'natural_person',
  beneficiary_data: {
    legal_name: 'Jane Doe',
    date_of_birth: '1990-04-12',
    country_of_citizenship: 'US',
    identification: { type: 'ssn', value: '123-45-6789' },
    residential_address: {
      line_1: '123 Market St',
      line_2: null,
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country_code: 'US',
    },
  },
})

// 2. Create the account for that holder
const account = await client.accounts.create({
  account_program_id: '550e8400-e29b-41d4-a716-446655440002',
  account_holder_id: holder.id,
})

Step	Endpoint
Register the holder	POST `/v1/account_holders`
Create the account	POST `/v1/accounts`

The Virtual Account opens in pending and is activated by Augustus once verification clears, usually within minutes. If additional information is required (EDD, sanctions hit, or identity mismatch), the Virtual Account stays pending and Augustus contacts you with next steps.

List accounts

With no filter, returns accounts owned directly by your business entity. With account_program_id, returns the Virtual Accounts under that Account Program.

2026-05-01

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
for await (const account of client.accounts.list({
  account_program_id: '550e8400-e29b-41d4-a716-446655440002',
})) {
  // process account
}

Get an account balance

2026-05-01

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
const balance = await client.accounts.retrieveBalance('9f8c1d2e-4b7a-4c3d-9e1f-2a5b6c7d8e90')

console.log(balance)
// {
//   type: 'account_balance',
//   account_id: '9f8c1d2e-4b7a-4c3d-9e1f-2a5b6c7d8e90',
//   amount: '5230.55',
//   currency: 'USD',
//   as_of: '2026-08-15T14:32:00Z',
// }

Basics

Accounts

Transactions

Payments

Conversions

Loans

Pay by Bank

FBO with Virtual Accounts

Two primitives

Status model

Beneficiary data: what you provide for each Account Holder

Money in: receiving funds

Money out: sending funds

Integration

Open a Virtual Account

List accounts

Get an account balance

​FBO with Virtual Accounts

​Two primitives

​Status model

​Beneficiary data: what you provide for each Account Holder

​Money in: receiving funds

​Money out: sending funds

​Integration

​Open a Virtual Account

​List accounts

​Get an account balance

FBO with Virtual Accounts

Two primitives

Status model

Beneficiary data: what you provide for each Account Holder

Money in: receiving funds

Money out: sending funds

Integration

Open a Virtual Account

List accounts

Get an account balance