Documentation Index
Fetch the complete documentation index at: https://doc.raliopay.com/llms.txt
Use this file to discover all available pages before exploring further.
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
| Rail | Description |
|---|---|
SEPA | Single Euro Payments Area transfers (EUR) |
ACH | US Automated Clearing House transfers (USD) |
Lifecycle and states
A vIBAN goes through the following states:| State | Description |
|---|---|
PENDING | Created and awaiting compliance review. Cannot receive funds yet. |
ACTIVE | Approved and operational. The accountNumber and bic (or routingNumber) are available for use. |
REJECTED | Compliance rejected the request. Check rejectionReason for details. A new vIBAN must be requested. |
INACTIVE | The vIBAN was deactivated and no longer accepts incoming transfers. |
Newly created vIBANs always start in
PENDING and require compliance approval before becoming ACTIVE. 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
Identify the target account
Use List user accounts to locate the
accountId you want to attach the vIBAN to.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.Wait for compliance approval
Subscribe to the
viban_activated and viban_failed webhook events to be notified when the review is resolved.Share the account details
Once
ACTIVE, the response includes the accountNumber, bic, routingNumber, and bankName your end users need to send funds.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.