Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augustus.com/llms.txt

Use this file to discover all available pages before exploring further.

Virtual Accounts is in beta with a controlled rollout. Reach out to will@augustus.com to enable it for your account.
Virtual Accounts are sub-ledgered balances with unique account identifiers, sitting under a bank account you hold with Augustus. Virtual Accounts provide the infrastructure for you to easily implement accounts for customers on your platform with automated reconciliation and the ability to send and receive payments in the names of your customers. The primary use case for Virtual Accounts is FBO with Virtual Accounts: you open a client funds account with Augustus For Benefit Of (FBO) your customers. You 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 FedNow
  • Its own sub-ledger and balance
  • The end-user’s name for sending/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. Your master FBO account at Augustus, held in your name for the benefit of your customers. From your perspective this is one account; sub-ledgering and named payments are layered on top. One currency per Program: a setup needing both USD and EUR uses two Programs.
Sponsored vs. unsponsored Programs. Two Account Program variants exist (Program Managed and Sponsored). Which one fits your use case depends on your licensing and use case. Talk to your account manager to confirm which is suitable.
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 end-user’s beneficiary data is collected. Used to receive funds in and send funds out in the name of a single end-user.

​
Status model

Accounts and Programs share the same status model.
StatusBehaviour
pendingNewly opened, not yet activated. Augustus typically activates within minutes. Some accounts require additional information (e.g. enhanced due diligence) before activation.
activeNormal. Pay-ins and pay-outs allowed.
frozenNo pay-ins or pay-outs. Reversible: call /unfreeze to return to active.
closedTerminal. 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 Virtual Account

To open a Virtual Account, send Augustus the beneficiary data for the end-user. Required CIP fields differ by beneficiary type.
  • Legal name
  • Residential address
  • Date of birth
  • Identification: SSN, ITIN, or government ID number
  • Country of citizenship
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.
RailSpeedUse case
ACH1–3 business daysLow-cost retail flows
FedWireSame-dayHigh-value or business-hours wires
FedNowReal-time, 24/7/365Instant funding
SWIFT (USD)Same/next-dayInternational 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 pay-outs 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 Pay-on-Behalf-of (PoBo). The Virtual Account holder’s name will appear to the receiving bank and beneficiary. Funds are debited from the Virtual Account atomically at payout initiation. Payout request and response shapes follow the existing Payouts API; the only addition is that the source account is a Virtual Account.

​
Integration

The endpoints below show the shape of the API and the key calls you’ll make to integrate Virtual Accounts. Full reference, including all status-change endpoints, will live in the API reference. All Account and Account Program endpoints sit under the v1/accounts/* and v1/account-programs/* namespaces. They follow the same auth, error, and pagination conventions as the rest of the Banking API.
Sandbox. All Virtual Account flows are available in test mode with simulated rail movements. See Test Mode.

​
Open a Virtual Account

2026-05-01
import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
const account = await client.accounts.create({
  account_program_id: 'ap_01HABC...',
  account_type: 'virtual_account',
  beneficiary_data: {
    legal_name: 'Jane Doe',
    date_of_birth: '1990-04-12',
    country_of_citizenship: 'US',
    identification: { type: 'ssn', value: '***-**-1234' },
    residential_address: {
      street_line_1: '123 Market St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country: 'US',
    },
  },
})
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, identity mismatch), the Virtual Account stays pending and Augustus contacts you with next steps.

​
List accounts

With no parent_id, returns accounts owned directly by your business entity; with parent_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({
  parent_id: 'ap_01HABC...',
})) {
  // 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('acc_01HXYZ...')

console.log(balance)
// {
//   type: 'account_balance',
//   account_id: 'acc_01HXYZ...',
//   amount: '5230.55',
//   currency: 'USD',
//   as_of: '2026-09-15T14:32:00Z',
// }

​
Feedback

This guide is a v1 and we welcome any feedback. Email will@augustus.com or reach out to your account manager to set up a call.