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: 
PENDING → IN_PROGRESS → ACTIVE → INACTIVE
   ↘           ↘
    REJECTED ←─

​
State Definitions

StateDescription
PENDINGvIBAN has been requested and is awaiting compliance review
IN_PROGRESSCompliance has approved the request and the vIBAN is being provisioned by the provider. Bank coordinates are not yet available
ACTIVEvIBAN has been issued by the provider and is ready to receive incoming transfers
REJECTEDThe vIBAN request was rejected by compliance or failed to be provisioned by the provider
INACTIVEThe vIBAN was previously active and has been deactivated; it can no longer receive incoming funds
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.
EventDescription
viban_activatedNotifies when a vIBAN has been approved and provisioned (state → ACTIVE)
viban_failedNotifies when a vIBAN request has been rejected or failed (state → REJECTED, from PENDING or IN_PROGRESS)
viban_deactivatedNotifies 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.
RailDescription
SEPASingle Euro Payments Area — IBAN/BIC, EUR transfers
ACHAutomated 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.