Skip to main content

Request a virtual account for a customer

POST/partner/v1/virtual-accounts
Auth Bearer tokenScope partner.write

Issues a virtual account (bank details) for one of your customers in one fiat currency, and returns it. The bank account is issued in your customer's name, so their payers see their name when they pay.

Money a payer sends to a customer's account lands in your balance in that currency. ryno keeps no balance for your customer: you track what you owe each customer.

Asking again for the same customer and currency returns the account already issued, so this call needs no Idempotency-Key. Your customer must be active. The currency must be an active fiat currency with a bank rail for you. Your own accounts are issued when your wallet is set up, so customerId is required.

Body​

customerIduuidrequired

One of your customers. Another partner's customer, a customer still being verified, and your own customer id all return 404 partner.sub_customer_not_found.

currencystringrequired

A currency code of 3 or 4 characters, for example NGN. Case does not matter. Only active fiat currencies can be issued: a crypto code such as USDT returns 400 partner.currency_not_supported.

Response​

valueobject

The customer's account in that currency.

Show propertiesHide properties
virtualAccountIduuid

ryno's id for the account.

currencystring

The currency a payer sends, for example NGN.

purposestring | null

Always null for a customer's account.

providerNamestring

The bank partner that issued the account.

fundingRailstring

How the payer pays, for example BankTransfer.

statusstring

Always Active: only active accounts are returned. Kept for future states.

accountNumberstring | null
accountNamestring | null

The name the payer's bank shows: your customer's name.

bankNamestring | null
bankCodestring | null
sortCodestring | null

The UK sort code, where the bank partner issued one (GBP accounts). null otherwise.

ibanstring | null

The IBAN, where the bank partner issued one (for example EUR accounts). null otherwise.

isPrimaryboolean

Always true: only the account payers are given is returned. Kept for compatibility.

createdDateUtcstring

When the account was issued, in UTC.

Errors​

CodeHTTPMeaning
Request.Invalid400The body is not valid JSON, or customerId is not a uuid.
partner.customer_id_required400customerId is missing.
partner.currency_not_supported400currency is missing, not 3 or 4 characters, unknown, switched off, or not a fiat currency.
partner.no_active_funding_rail400No bank rail can issue a permanent account in this currency for you. Contact support.
partner.wallet_not_active400Your balance in this currency is not active. Contact support.
Auth.Unauthorized401The token is missing or invalid.
Auth.Forbidden403The token is not a partner credential, or lacks partner.write.
partner.profile_not_active403Your partner account is not active. Contact support.
partner.customer_read_only403The customer is suspended or closed. Their accounts can still be listed.
partner.sub_customer_not_found404No customer of yours has that id.
partner.profile_not_found404Your partner account could not be found. Contact support.
partner.virtual_account_unavailable503No bank partner could issue an account right now. Nothing was issued; ask again later.

The 401, 429 and 503 responses from the API gateway use a different body. See Errors. A 500 is problem details, not this envelope.