Skip to main content
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:

​
State Definitions

IN_PROGRESS is an intermediate, internal state that does not fire a webhook. You may observe it when polling the Get vIBAN endpoint between approval and activation, but the only state transitions that trigger webhooks are the terminal ones (ACTIVE, REJECTED, INACTIVE).

​
Available Webhook Events

Each terminal state transition triggers a webhook event.

​
Rails

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

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