The International Bank Account Number (IBAN) is the unique identifier of a bank account as agreed upon by international standards.

An IBAN along with a BIC code are automatically assigned to every newly created Wallet. They are either Treezor IBANs or your own IBAN if you are a Regulated Institution or more broadly a Regulated Institution.

# Virtual IBANs

In addition to the automatically assigned IBAN, Virtual IBANs can be created. Wallets can have as many Virtual IBANs as you see fit, to answer a large variety of use cases such as:

  • Communicating dedicated IBANs for specific users and/or usage, thus better categorizing funds movements.
  • Facilitating litigation handling, deactivating a Virtual IBAN without impacting the corresponding Wallet.

Virtual IBANs support the same operations as regular IBANs, but with limitations to prevent abuses:

  • Single direction – Define whether your Virtual IBAN supports outgoing funds SDD or incoming funds SCT.
  • Timeframe – Limit your Virtual IBAN usage between two specified dates.
  • Number of transaction – Set a maximum number of transactions for your Virtual IBAN.
  • Maximum amount – Set a maximum cumulated amount for your Virtual IBAN.
Note icon

Note – Declined transfers don't impact limits

A declined SCT or SDD is ignored by Virtual IBAN limits (its doesn't count towards maxUsage or maxAmount restrictions).

# Creating a Virtual IBAN

# Parameters

Attribute Type Description
walletId integer The unique identifier of the Wallet to which the Virtual IBAN is associated. Must be a walletType of 9 or 10.
typeId integer The type of IBAN, allowing for a specific transfer direction. Can be:
validFrom string The date from which the Virtual IBAN validity starts. Defaults to today's date and must be set in the future.
Format: YYYY-MM-DD
validTo string The date from which the Virtual IBAN validity ends. Must be set after the validFrom date.
Format: YYYY-MM-DD
maxUsage integer The maximum number of transactions allowed (0 = unlimited).
maxAmount string (float) The maximum cumulated amount of all transactions ("0.00" = unlimited).
reference string Custom field for your internal reference of the Virtual IBAN.
Max. length: 255 characters.
tag string Custom attribute that you can use as you see fit.
Learn more in the Object tags article.

Here is the request to create a Virtual IBAN:

Here is an example of {payload}:

Returns a Virtual IBAN object, containing its id, the IBAN itself and additionnal information.

Bulb icon

Tip – All your Virtual IBANs have the same BIC

All IBANs emitted by Treezor have the following BIC TRZOFR21XXX unless you are a Payment Institution or more broadly a , in which case, you have your own BIC.

# Retrieving a Virtual IBAN

You can use the following request with the virtualIbanId as a path parameter to retrieve a Virtual IBAN.

Returns the corresponding Virtual IBAN object.

# Deleting a Virtual IBAN

For legal reasons, Virtual IBANs cannot be deleted. The only way to do so is for the Virtual IBAN to go past its validTo date.

While the validTo date can't be set in the past, you may still update it to be in the very near future by using the Update Virtual IBAN request.

Returns the updated Virtual IBAN object.

# Endpoints

Endpoint Description Scope
/v1/virtualibans Create a Virtual IBAN read_write
/v1/virtualibans Search Virtual IBANs read_only
/v1/virtualibans/{virtualIbanId} Retrieve a specific Virtual IBAN read_only
/v1/virtualibans/{virtualIbanId} Update a Virtual IBAN read_write
Updated on: 4/30/2024, 12:23:09 PM