> ## 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.

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Virtual Accounts (FBO)

> Issue accounts for your customers (retail & business) - accounts with unique account identifiers, under your Augustus account.

*Virtual Accounts are in beta. Contact [will@augustus.com](mailto:will@augustus.com) to enable them on your account.*

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 FedNow.
* 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.

```mermaid theme={null}
flowchart LR
  M[Your business] --> AP[Account Program<br/>FBO master account<br/>USD]
  AP --> VA1[Virtual Account<br/>End-user A]
  AP --> VA2[Virtual Account<br/>End-user B]
  AP --> VA3[Virtual Account<br/>End-user C]
```

### 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.

<Note>
  **Sponsored vs. unsponsored Programs.** Two Account Program variants exist (`Program Managed` and `Sponsored`). The right variant depends on your licensing and use case. Talk to your account manager to confirm which is suitable.
</Note>

**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.

| 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 pay-outs allowed.                                                                                                                                       |
| `frozen`  | No pay-ins or pay-outs. Reversible — call `/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 Virtual Account

To open a Virtual Account, send Augustus the beneficiary data for the end-user. Required CIP fields differ by beneficiary type.

<Tabs>
  <Tab title="Individual">
    * Legal name
    * Residential address
    * Date of birth
    * Identification: SSN, ITIN, or government ID number
    * Country of citizenship
  </Tab>

  <Tab title="Legal Entity">
    * Legal business name
    * DBA (if applicable)
    * Registered address
    * Physical address
    * Registration number (EIN / TIN)
    * Year of incorporation
    * State of incorporation
    * Country of incorporation (if non-US)
    * Beneficial owners (at least one; same CIP fields as an individual)
    * Control person (same CIP fields as an individual, plus title)
  </Tab>
</Tabs>

<Note>
  Open at most one Virtual Account per entity under each Account Program.
</Note>

***

## 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**         | 1–3 business days   | Low-cost retail flows                       |
| **FedWire**     | Same-day            | High-value or business-hours wires          |
| **FedNow**      | Real-time, 24/7/365 | Instant funding                             |
| **SWIFT (USD)** | Same/next-day       | 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 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 appears 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](/docs/payout/payout) — 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. The full reference, including all status-change endpoints, lives 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 [2026-05-01 API](/v1/introduction).

<Note>
  **Sandbox.** All Virtual Account flows are available in test mode with simulated rail movements. See [Test Mode](/docs/basics/test-mode-sandbox).
</Note>

### Open a Virtual Account

```ts 2026-05-01 theme={null}
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, or 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.

```ts 2026-05-01 theme={null}
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

```ts 2026-05-01 theme={null}
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',
// }
```