Add Virtual Accounts

The customer must already be onboarded and active before you add a feature. You get customerId from the application.approved webhook — see Onboard a Customer and The Onboarding Lifecycle. Calling features before the customer is active returns CUSTOMER_NOT_ONBOARDED.

Test this flow in sandbox. Drive it end-to-end with simulated money and deterministic controls — start with the sandbox quickstart, then deposit simulation for this flow, and the cheat sheet for every magic value and simulate endpoint.

Flow

Add Virtual Accounts by submitting a feature application against an existing customer. The integration:

Discover the customer’s feature requirements.
Submit a virtual_account feature application.
Listen for application.approved or application.rejected webhooks (with applicationType: "virtual_account").
Listen for virtual_account.activated.
Fetch the customer’s Virtual Accounts and read balances[] plus depositInstructions[].

Request The Feature

Discover any extra requirements for the customer:

curl 'https://api.conduit.financial/v2/customers/{customerId}/features/requirements?type=virtual_account' \
  -H "x-api-key: YOUR_API_KEY"

Like the onboarding flow, the discovery response lists any required fields and documents. When present, collect them and include them in the submit body below. When the response asks for nothing extra, submit with just type and asset. Submit the Virtual Account feature application for the target asset. Idempotency-Key is required — without it the call returns IDEMPOTENCY_KEY_REQUIRED.

curl https://api.conduit.financial/v2/customers/{customerId}/features \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "virtual_account",
    "asset": { "code": "USD" }
  }'

The endpoint returns 202 Accepted with a Virtual Account feature application carrying its own application id. Track it through the application.approved and application.rejected webhooks with applicationType: "virtual_account".

Listen For Activation

Once the feature application is approved, listen for virtual_account.activated to know the Virtual Account is usable. Deposit instructions populate once the Virtual Account’s status is active. See Webhooks and Virtual Accounts.

Retrieve Deposit Instructions

After activation, fetch the Virtual Accounts for the customer:

curl https://api.conduit.financial/v2/customers/{customerId}/virtual-accounts \
  -H "x-api-key: YOUR_API_KEY"

The response contains VA-level balances and deposit instructions. It does not include provider bank accounts.

{
  "data": [
    {
      "id": "vac_...",
      "asset": { "code": "USD" },
      "status": "active",
      "balances": [
        {
          "available": { "code": "USD", "amount": "0.00" },
          "pending": { "code": "USD", "amount": "0.00" },
          "frozen": { "code": "USD", "amount": "0.00" }
        }
      ],
      "depositInstructions": [
        {
          "type": "domestic_usd",
          "accountNumber": "123456789",
          "beneficiaryName": "Example Customer",
          "beneficiaryAddress": "1 Main St, New York, NY",
          "bank": {
            "legalName": "Example Bank",
            "address": "2 Bank St, New York, NY"
          },
          "rails": [
            { "rail": "ach", "routingNumber": "021000021", "sameDayEligible": false },
            { "rail": "fedwire", "routingNumber": "021000021" },
            { "rail": "rtp", "routingNumber": "021000021", "networks": ["tch"] }
          ]
        }
      ],
      "activatedAt": "2026-04-30T00:00:00.000Z",
      "createdAt": "2026-04-30T00:00:00.000Z",
      "updatedAt": "2026-04-30T00:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "cursor",
    "nextCursor": null,
    "previousCursor": null,
    "total": 1
  }
}

Retrieve one Virtual Account when you have its id:

curl https://api.conduit.financial/v2/customers/{customerId}/virtual-accounts/{virtualAccountId} \
  -H "x-api-key: YOUR_API_KEY"

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Flow

Request The Feature

Listen For Activation

Retrieve Deposit Instructions

​Flow

​Request The Feature

​Listen For Activation

​Retrieve Deposit Instructions

Flow

Request The Feature

Listen For Activation

Retrieve Deposit Instructions