> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Accounts

> Client-facing account abstractions for receiving funds

## Overview

A Virtual Account is the customer-facing account abstraction for receiving funds in an asset. Clients see the Virtual Account, not the underlying provider bank accounts that Conduit provisions and manages internally.

Virtual Accounts are scoped to a customer and asset. For fiat assets, each active Virtual Account can expose deposit instructions grouped by collection rail, such as ACH, Fedwire, RTP, SWIFT, or SEPA.

## Lifecycle

| Status               | Meaning                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `pending_activation` | The Virtual Account has been requested and Conduit is provisioning provider-side backing accounts. |
| `active`             | At least one backing account is active and deposit instructions can be returned.                   |
| `disabled`           | The Virtual Account is no longer available for new deposits.                                       |

## Deposit Instructions

Deposit instructions are returned on the Virtual Account as `depositInstructions[]`. Each element is a **deposit block** — a discriminated union grouped by collection method rather than by individual rail. Branch on `type`.

A block names the **rail family** it collects on and carries its **currency as data**, so the two are independent: the family tells you which coordinates a payer needs, and `currency` tells you what the account holds. Never read the currency off the `type` string.

### Block types

Every block carries `currency` (the ISO currency code the account collects, for example `USD` or `EUR`), `beneficiaryName`, an optional `beneficiaryAddress`, an optional `beneficiaryPostalAddress`, an optional `bank`, an optional `paymentReference`, and a `rails[]` array.

| `type`        | Coordinates                                                                    | Description                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `us_domestic` | `accountNumber` plus one `routingNumber` per rail entry                        | Domestic US clearing (ACH, Fedwire, RTP). `rails[]` holds one entry per network the account collects on.                                                 |
| `swift`       | `accountNumber` or `iban`, plus the bank `bic` and an optional `correspondent` | International SWIFT transfer. `rails[]` holds exactly one entry.                                                                                         |
| `sepa`        | `iban` plus `bic`                                                              | Euro-area credit transfer, settling at the collecting bank with no US correspondent hop. `bic` is always present, and `rails[]` holds exactly one entry. |

A USD Virtual Account typically returns a `us_domestic` block, and a `swift` block as well when the collecting bank accepts international wires. A EUR Virtual Account returns a `sepa` block.

<Warning>
  These `type` values were previously `domestic_usd` and `swift_usd`, and blocks carried no `currency` field. If your integration branches on the old names, switch to `us_domestic` and `swift` and read the currency from `currency`.
</Warning>

### Beneficiary address

Each block carries the beneficiary address in two forms:

* `beneficiaryAddress` is a display string for a wire form. Conduit does not guarantee its layout: lines are left out when parts of the address are empty, so the number of lines changes between customers. Do not parse this string.
* `beneficiaryPostalAddress` is the same address in fields: `addressLine1`, `addressLine2`, `city`, `state`, `postalCode`, and `country` (ISO 3166-1 alpha-2). The field names match the `postalAddress` of a payout recipient, so you can pass the object through.

Both come from the customer's registered address, and both are left out when the customer has none on file. Conduit returns the two forms for a business customer only. An individual customer receives neither form, whatever the customer record holds.

`addressLine2`, `state`, and `postalCode` are present only when the customer has them on file.

A fiat payout keeps its own rules for the address you send it, so check the object against them before you send it:

* The payout needs a `postalCode` for each country that operates one. A beneficiary with no postal code on file does not satisfy this.
* The payout limits `addressLine1` and `addressLine2` to 120 characters, and `city` and `state` to 80. A customer record accepts longer values.
* The payout accepts letters, numbers, whitespace, and the punctuation marks `' ’ – — - . , ; : & # / ( ) @ + _ ? !` only. A customer record accepts other characters, such as a quotation mark.

### Rail entries

Each block contains a `rails[]` array naming the individual networks available for that block.

Each `us_domestic` rail entry includes `routingNumber` and, depending on the rail:

* **ach**: `sameDayEligible` (boolean) reflects same-day ACH eligibility for this bank.
* **fedwire**: no `sameDayEligible` or `networks` fields.
* **rtp**: `networks` lists the supported instant-payment networks (for example `["tch", "fednow"]`); `fednowCap` is set when `fednow` is supported. Both networks share the one `routingNumber` on the entry, and the sending bank chooses between them.
* **swift** and **sepa** entries carry only the `rail` discriminant.

### Bank information

The optional `bank` object on each block contains `legalName`, `address`, an optional `postalAddress`, and `bic`. It is omitted when the collecting bank is not disclosed for that block. On a `sepa` block the `bic` you need to send is the top-level `bic` field, which is always present whether or not `bank` is.

The bank address comes in the same two forms as the beneficiary address: `address` is a display string you must not parse, and `postalAddress` is the same address in the `addressLine1`, `addressLine2`, `city`, `state`, `postalCode`, and `country` fields, with `country` as an ISO 3166-1 alpha-2 code. The `correspondent` object on a `swift` block carries both forms too.

`postalAddress` is present only for banks Conduit has recorded a structured address for, so read `address` when it is absent. Conduit records the two forms separately and does not derive one by parsing the other.

Conduit does not expose provider names, bank-account ids, payment-routing rule ids, or raw provider metadata in client-facing Virtual Account responses.

## API Surface

Use the customer-scoped read endpoints to retrieve Virtual Accounts:

* `GET /v2/customers/:customerId/virtual-accounts`
* `GET /v2/customers/:customerId/virtual-accounts/:virtualAccountId`

The list endpoint accepts an optional `?asset=USD` query parameter to filter by asset code (case-insensitive). Both endpoints require the customer to have the `virtual_account` feature enabled.