> ## 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.

# Overview

> Understand how Virtual IBANs work in RalioPay and how to create, manage, and deactivate them via API.

## 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.                                                              |
| `IN_PROGRESS` | Compliance has approved the request and the vIBAN is being provisioned by the provider. Bank information is not yet available. |
| `ACTIVE`      | Approved and operational. The `accountNumber` and `bic` (or `abaRoutingCode`) are available for use.                           |
| `REJECTED`    | Compliance rejected the request, or provisioning failed. Check `rejectionReason` for details. A new vIBAN must be requested.   |
| `INACTIVE`    | The vIBAN was deactivated and no longer accepts incoming transfers.                                                            |

<Info>
  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`](/webhooks-events/viban/viban-activated) or [`viban_failed`](/webhooks-events/viban/viban-failed) webhook once the review is completed.
</Info>

## Available endpoints

* [List vIBANs](/api-reference/account-vibans/list-vibans): returns all vIBANs for a given account.
* [Create vIBAN](/api-reference/account-vibans/create-viban): submits a new vIBAN request for compliance review.
* [Get vIBAN](/api-reference/account-vibans/get-viban): retrieves details of a specific vIBAN by ID.
* [Update vIBAN alias](/api-reference/account-vibans/update-viban-alias): renames the `name` (alias) of an existing vIBAN.
* [Deactivate vIBAN](/api-reference/account-vibans/deactivate-viban): deactivates a vIBAN so it no longer accepts incoming transfers.

## How to use them

<Steps>
  <Step title="Identify the target account">
    Use [List user accounts](/api-reference/user-accounts/list-user-accounts) to locate the `accountId` you want to attach the vIBAN to.
  </Step>

  <Step title="Request a new vIBAN">
    Call [Create vIBAN](/api-reference/account-vibans/create-viban) with a `name` (alias) and the desired `rail` (`SEPA` or `ACH`). The vIBAN is created in `PENDING` state.
  </Step>

  <Step title="Wait for compliance approval">
    Subscribe to the [`viban_activated`](/webhooks-events/viban/viban-activated) and [`viban_failed`](/webhooks-events/viban/viban-failed) webhook events to be notified when the review is resolved.
  </Step>

  <Step title="Share the account details">
    Once `ACTIVE`, the response includes the `accountNumber`, `bic`, `abaRoutingCode`, and `bankName` your end users need to send funds.
  </Step>

  <Step title="Deactivate when no longer needed">
    Call [Deactivate vIBAN](/api-reference/account-vibans/deactivate-viban) to stop receiving transfers on that account number. You will receive a [`viban_deactivated`](/webhooks-events/viban/viban-deactivated) event.
  </Step>
</Steps>

<Check>
  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.
</Check>