Skip to main content

​
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

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

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