Create a virtual account

Creates a virtual account: a permanent set of bank details on an incoming rail and currency, tied to a destination wallet. Money that arrives on the account is converted to the output asset and settled to that wallet - see Virtual accounts for what the product does.

Creating virtual accounts needs the virtual-accounts permission on your API key. It is granted separately from the rest of your key’s setup - ask us. A key without it gets 403 permission_denied from every endpoint in this section. See Authentication.

Request

The account is opened for a user you have already onboarded, and it inherits the corridor agreed on your account: which rail and currency it accepts, which asset the incoming money is converted into, and which network it settles on. Those are not passed per request, so a browser cannot redirect where money lands.

string

required

The id returned when the user was onboarded and their identity result shared with the banking partner. See Bank transfers.

string

required

The id of the wallet registered for that user at onboarding. It is the wallet the settled stablecoin is delivered to.

Response

string

The virtual account id. Keep it - see the note on reading accounts back below.

object

The bank details to display, plus the reference that ties a transfer to this account. The fields depend on the rail: an IBAN with a SWIFT code for SEPA, an account number with a routing number for ACH, an account number with a sort code for UK rails, a CLABE for SPEI. Render what comes back rather than assuming a shape, and show the reference exactly as returned - a transfer without it has to be attributed by hand.

number

Your fee on this account, in basis points (100 bps = 1%), taken from money arriving on it.

Store what you get back. Reading an account back after creation is not available yet: the get, list and update endpoints answer 501 not_implemented until the banking partner integration can serve them. Keep the details and the reference from this response rather than planning to fetch them later.

Some currencies provision asynchronously (USD, AED, COP): the details arrive moments after the account is created rather than with it. Until read-back exists, retry creation for the same user rather than polling - it is idempotent per user and wallet.

curl -X POST "$RHEON_API/v1/virtual-accounts" \
  -H "Authorization: Bearer $RHEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct_8f2c91d0a4",
    "walletId": "wlt_5b71e0c3"
  }'

{
  "id": "va_8f2c91d0a4",
  "details": {
    "iban": "IE25XXXX99035504017602",
    "bic": "XXXXIE2D",
    "beneficiary": "Jane Doe",
    "reference": "RHN-84921"
  },
  "applicationFeeBps": 25
}

Errors

HTTP	`code`	When
400	`invalid_request`	A field is missing or malformed, or the rail does not support the currency.
401	`unauthorized`	Missing, malformed, or unknown API key.
403	`permission_denied`	Your key does not carry the virtual-accounts permission.
403	`chain_not_allowed`	Your key is not enabled for `chain` as a destination.
429	`rate_limited`	Over your key’s rate limit.
502	`upstream_error`	The banking partner is unavailable.
500	`internal`	Unexpected server error.

Getting started

Crypto deposits

Card payments

Bank transfers

Virtual accounts

Reference

Create a virtual account

Request

Response

Errors

​Request

​Response

​Errors

Request

Response

Errors