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

# Virtual accounts

> Issue permanent bank details per user. Money that arrives is converted and settled to a wallet automatically.

A virtual account is a set of real bank details - IBAN, SWIFT, or local rails -
issued to one of your users and kept for good. Your user pays it from their own
bank, like any other transfer. What arrives is converted and settled as stablecoin
to the wallet and chain you attached to that account, with no reconciliation on
your side.

<Note>
  **Provider sandbox on this deployment.** Accounts open against the banking
  partner's sandbox: test bank details, no real transfer, settlement on a testnet.
  Whether the read-back calls answer is stated by `readBack` in
  [`GET /v1/config`](/api-reference/configuration/what-this-key-may-use).
</Note>

## What it is for

Each account behaves as a programmable collection point:

* **Collection** - one payer, one permanent set of details, any number of transfers.
* **Conversion** - fiat that lands is converted to the output asset you set on the
  account.
* **Settlement** - the converted amount is delivered to the wallet you attached, on
  the chain you named.
* **Attribution** - funds arrive already tied to one user, so you are not matching
  names on statements.

Typical uses: a fintech giving every customer their own deposit IBAN; a marketplace
giving each seller a collection account that settles on-chain; a platform
collecting EUR and holding balances in USDC.

## How it works

<Steps>
  <Step title="Verify the user once">
    Identity is checked once and reused across rails - see [Rheon ID](/concepts/customers-and-identity).
    The user consents to sharing the result with the banking partner; a returning
    user is not asked again.
  </Step>

  <Step title="Open the account">
    You name the destination wallet, the chain, and the output asset. You get back
    the bank details to display and the fee that applies. The wallet is fixed from
    that moment - an open account cannot be pointed at a different one.
  </Step>

  <Step title="Show the details">
    Display the account details and the reference exactly as returned. A transfer
    that arrives without the reference has to be attributed by hand.
  </Step>

  <Step title="Money arrives and settles">
    The user sends a normal bank transfer. Conversion and settlement happen without
    another call from you. Bank transfers clear in hours or days, not seconds - do
    not build a UI that expects the user to wait on screen.
  </Step>

  <Step title="Track it">
    Poll for funding status until the transfer is delivered, then credit the user.
  </Step>
</Steps>

## What an account carries

| Setting | What it does |
| - | - |
| Destination wallet | The address the settled stablecoin is delivered to. Attached when the account is opened, and fixed for the life of the account. |
| Chain | The network settlement happens on. |
| Output asset | What the incoming fiat is converted into. |
| Incoming rail and currency | Which bank rail and currency the account accepts, e.g. EUR over SEPA. |
| Fee | Your fee, in basis points, applied to money arriving on that account. |
| Reference | The string the payer must include, so the transfer is attributed automatically. |

<Warning>
  **The destination wallet cannot be changed after the account is opened.** The
  banking partner binds an account to one wallet for its whole life; only the fee is
  amendable. If a user needs to settle somewhere else, open a second account for the
  new wallet and show them those details - the old account keeps working and keeps
  settling to the old wallet, so stop showing it once you have switched.
</Warning>

## Fees

Your fee is set in basis points on the account and taken from the incoming amount.
The banking partner charges its own fee on top of that, so what the user receives is
smaller than the amount minus your fee alone. If you show a "you send / you receive"
figure before the transfer, quote it - do not compute it from your own fee only.
How the layers are built, and the bounds on a markup or subsidy, are on
[Fees](/fees).

## API

Two ways in, depending on who drives:

* **The buyer-facing flow** - onboard the user, open the account, poll for funding.
  Three calls, in order: the
  [Bank transfers reference](/api-reference/bank-transfers/onboard-a-bank-transfer-user).
* **Direct management** - create, read, update the fee, and list virtual accounts
  from your backend, starting at
  [Create a virtual account](/api-reference/virtual-accounts/open-a-virtual-account). Creating
  accounts needs the virtual-accounts permission on your API key - see
  [Authentication](/api-reference/authentication).

<Note>
  **Errors on this endpoint carry the banking partner's own codes.** The envelope is
  the platform one, but `code` and `fields` inside it are passed through from the
  banking partner unchanged rather than mapped to the platform vocabulary - a
  deliberate exception to the one-error-format story. Branch on the HTTP status
  first; treat `code` as a string to log and show, not a fixed set to enumerate.

  ```json theme={null}
  {
    "error": {
      "code": "<the banking partner's code>",
      "message": "Human-readable detail from the banking partner",
      "fields": { "applicantInfo.nationality": "iso3166_1_alpha2" }
    }
  }
  ```
</Note>

## Currencies, rails, and limits

EUR, GBP, USD (ACH, wire, RTP, and SWIFT), AED, AUD, BRL, MXN, NGN, and COP, plus
stablecoin collection accounts on eight networks. Per-currency rails, who is allowed
to pay in, and the settlement ceilings are on [Coverage](/coverage); pricing is on
[Fees](/fees).

Two operational details worth building for:

* **Some accounts provision asynchronously** (USD, AED, COP). The details come back
  empty and populate moments later - poll rather than showing your user a blank
  screen.
* **Not every rail accepts a third-party payer.** GBP and AUD accept money only from
  the account holder. A transfer from someone else's account is not a payment you can
  credit.