Skip to main content
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:
  1. Discover the customer’s feature requirements.
  2. Submit a virtual_account feature application.
  3. Listen for application.approved or application.rejected webhooks (with applicationType: "virtual_account").
  4. Listen for virtual_account.activated.
  5. Fetch the customer’s Virtual Accounts and read balances[] plus depositInstructions[].

​
Request The Feature

Discover any extra requirements for the customer:
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. Add &asset=USD to discover the requirements for one currency only. Requirements can differ by currency, so pass the currency you are about to submit. When no banking partner can hold the currency you pass, this call returns NO_ELIGIBLE_PROVIDER instead of a requirements response — omit asset to see which currencies are available to the customer. Submit the Virtual Account feature application for the target asset. Idempotency-Key is required — without it the call returns IDEMPOTENCY_KEY_REQUIRED.
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". A rejection carries resubmittable: when it is true, correct the data and request the feature again; when it is false, the decision is final. A customer can hold one Virtual Account per currency. Submit the request again with a different asset to add another currency. A second request for a currency the customer already has returns FEATURE_ALREADY_EXISTS, and the message names that currency.

​
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. See Virtual Accounts for the full deposit-block union.
The response contains VA-level balances and deposit instructions. It does not include provider bank accounts.
A EUR Virtual Account returns a sepa block on the same endpoint. Send to the iban and the bic:
Retrieve one Virtual Account when you have its id:
The block 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.