What a Virtual IBAN is
A Virtual IBAN (vIBAN) is a dedicated bank account number attached to one of your accounts that allows your end users to receive funds by traditional bank transfer. Each vIBAN routes incoming funds to the underlying account it belongs to, so you can offer multiple receiving identities (per user, per purpose, per region) without opening additional bank accounts. Each vIBAN is associated with a single account and a single banking rail. Once active, any transfer received on that account number is credited automatically to the linked account.Supported rails
Lifecycle and states
A vIBAN goes through the following states:Newly created vIBANs always start in
PENDING and require compliance approval before becoming ACTIVE. They transition through IN_PROGRESS while the provider issues the bank coordinates; this is an intermediate state and does not fire a webhook. You will receive a viban_activated or viban_failed webhook once the review is completed.Available endpoints
- List vIBANs: returns all vIBANs for a given account.
- Create vIBAN: submits a new vIBAN request for compliance review.
- Get vIBAN: retrieves details of a specific vIBAN by ID.
- Update vIBAN alias: renames the
name(alias) of an existing vIBAN. - Deactivate vIBAN: deactivates a vIBAN so it no longer accepts incoming transfers.
How to use them
1
Identify the target account
Use List user accounts to locate the
accountId you want to attach the vIBAN to.2
Request a new vIBAN
Call Create vIBAN with a
name (alias) and the desired rail (SEPA or ACH). The vIBAN is created in PENDING state.3
Wait for compliance approval
Subscribe to the
viban_activated and viban_failed webhook events to be notified when the review is resolved.4
Share the account details
Once
ACTIVE, the response includes the accountNumber, bic, abaRoutingCode, and bankName your end users need to send funds.5
Deactivate when no longer needed
Call Deactivate vIBAN to stop receiving transfers on that account number. You will receive a
viban_deactivated event.Always validate the vIBAN
state is ACTIVE before sharing the accountNumber with end users — funds sent to a PENDING or REJECTED vIBAN will not be credited.