Skip to main content

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 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 → ACTIVE → INACTIVE
        ↘ REJECTED

​
State Definitions

StateDescription
PENDINGvIBAN has been requested and is awaiting compliance review and provisioning by the provider
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

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