Virtual IBANs
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Virtual IBANs (vIBANs) allow customers to receive payments to their main account through alternate IBANs.

A primary use case is automatic reconciliation. Instead of filtering transactions by the description field, customers can issue a unique vIBAN for specific invoices or clients. All funds sent to a vIBAN are automatically routed to the master account.

Key characteristics

Routing: Incoming payments to a vIBAN appear as bookings on the master account.
Identification: Bookings received via a vIBAN include the receiver_iban_virtual attribute.
No Balance: vIBANs do not hold funds independently; they are purely routing addresses.

Limitations

Receive Only: vIBANs support SEPA Credit Transfers (SCT) only. They cannot be used for outgoing payments or SEPA Direct Debits (SDD).
No Cards: You cannot link a debit card to a vIBAN.

Integration steps

1. Create a vIBAN

Call this endpoint to generate a new virtual IBAN for an existing account.

POST /v1/accounts/{account_id}/virtual_ibans

Create vIBAN

View API specification.

2. Identify incoming funds

When a payment is received via a vIBAN, the standard BOOKING webhook is triggered.

The booking object will contain the receiver_iban_virtual field, which you can use to identify the source (e.g., match it to a specific invoice).

Booking Example:

{
  "id": "booking_123",
  "amount": { "value": 5000, "currency": "EUR" },
  "recipient_iban": "DE_MASTER_IBAN", 
  "receiver_iban_virtual": "DE_VIRTUAL_IBAN_XYZ" 
}

Reconciliation Tip: You can retrieve only the bookings associated with a specific vIBAN by using the filter parameter:

GET /v1/accounts/{account_id}/bookings?filter[receiver_iban_virtual]=DE_VIRTUAL_IBAN_XYZ

3. Disable a vIBAN

If a vIBAN is no longer needed (e.g., the invoice is paid), you can disable it.

PATCH /v1/accounts/{account_id}/virtual_ibans/{virtual_iban_id}/disable

Disable vIBAN