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

# Virtual IBAN Webhooks Overview

> Virtual IBAN-related webhook events overview

Virtual IBAN webhooks notify your system about changes in the lifecycle of a vIBAN.\
A vIBAN is a dedicated, named bank coordinate (IBAN/BIC for SEPA, routing/account number for ACH) bound to one of your wallets so that incoming bank transfers can be automatically routed to it.

These events allow you to:

* Display the vIBAN coordinates to the end user once they are issued
* React to compliance approval or rejection
* Update the UI when a vIBAN is deactivated
* Keep your internal records in sync with the vIBAN state

***

# Virtual IBAN Lifecycle

A vIBAN moves through the following states:

```
PENDING → IN_PROGRESS → ACTIVE → INACTIVE
   ↘           ↘
    REJECTED ←─
```

## State Definitions

| State        | Description                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| PENDING      | vIBAN has been requested and is awaiting compliance review                                                                     |
| IN\_PROGRESS | Compliance has approved the request and the vIBAN is being provisioned by the provider. Bank coordinates are not yet available |
| ACTIVE       | vIBAN has been issued by the provider and is ready to receive incoming transfers                                               |
| REJECTED     | The vIBAN request was rejected by compliance or failed to be provisioned by the provider                                       |
| INACTIVE     | The vIBAN was previously active and has been deactivated; it can no longer receive incoming funds                              |

<Info>
  `IN_PROGRESS` is an intermediate, internal state that does **not** fire a webhook. You may observe it when polling the [Get vIBAN](/api-reference/account-vibans/get-viban) endpoint between approval and activation, but the only state transitions that trigger webhooks are the terminal ones (`ACTIVE`, `REJECTED`, `INACTIVE`).
</Info>

***

# Available Webhook Events

Each terminal state transition triggers a webhook event.

| Event              | Description                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| viban\_activated   | Notifies when a vIBAN has been approved and provisioned (state → ACTIVE)                                      |
| viban\_failed      | Notifies when a vIBAN request has been rejected or failed (state → REJECTED, from `PENDING` or `IN_PROGRESS`) |
| viban\_deactivated | Notifies when a previously active vIBAN has been deactivated (state → INACTIVE)                               |

***

# Rails

A vIBAN is issued on a specific payment rail. The `rail` field in the webhook payload identifies which one.

| Rail | Description                                                   |
| ---- | ------------------------------------------------------------- |
| SEPA | Single Euro Payments Area — IBAN/BIC, EUR transfers           |
| ACH  | Automated Clearing House — routing number/account number, USD |

***

# Important Behavior

* `viban_activated` is the signal that the vIBAN coordinates (`iban`, `bic`) are final and safe to expose to the end user.
* `viban_failed` carries a human-readable `reason` describing why the vIBAN could not be issued.
* `viban_deactivated` echoes the last known `iban` for traceability, but the account will no longer accept incoming transfers.
* Use `vibanId` for reconciliation against the vIBAN resource and `accountId` to identify the wallet it is bound to.