IBAN ​

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 ​

AttributeTypeDescription
walletId integerThe unique identifier of the Wallet to which the Virtual IBAN is associated. Must be a walletType of 9 or 10.
typeId integerThe type of IBAN, allowing for a specific transfer direction. Can be:
validFromstringThe date from which the Virtual IBAN validity starts. Defaults to today's date and must be set in the future.
Format: YYYY-MM-DD
validTostringThe date from which the Virtual IBAN validity ends. Must be set after the validFrom date.
Format: YYYY-MM-DD
maxUsageintegerThe maximum number of transactions allowed (0 = unlimited).
maxAmountstring (float)The maximum cumulated amount of all transactions ("0.00" = unlimited).
referencestringCustom field for your internal reference of the Virtual IBAN.
Max. length: 255 characters.
tagstringCustom 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:

bash
curl -X POST {baseUrl}/v1/virtualibans \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

json
{
	"walletId":{walletId},
	"typeId":2
}

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

json
{
    "virtualibans": [
        {
            "virtualibanId": 123456,
            "walletId": 0123456,
            "typeId": 2,
            "tag": "Test vIBAN",
            "reference": "",
            "validFrom": "2024-01-31",
            "validTo": null,
            "maxUsage": 10,			// 0 means there is no limit
            "maxAmount": "0.00",	// "0.00" means there is no limit
            "iban": "FR761679800001100000123455678",
            "createdDate": "2024-01-31 09:28:06",
            "numberOfTransactions": 0,
            "cumulatedAmount": "0.00",
            "updatedDate": null
        }
    ]
}
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.

bash
curl -X GET {baseUrl}/v1/virtualibans/{virtualIbanId} \
	--header 'Authorization: Bearer {accessToken}' \

Returns the corresponding Virtual IBAN object.

json
{
    "virtualibans": [
        {
            "virtualibanId": 123456,
            "walletId": 0123456,
            "typeId": 2,
            "tag": "Test vIBAN",
            "reference": "",
            "validFrom": "2024-01-31",
            "validTo": null,
            "maxUsage": 10,		
            "maxAmount": "0.00",	
            "iban": "FR761679800001100000123455678",
            "createdDate": "2024-01-31 09:28:06",
            "numberOfTransactions": 0,
            "cumulatedAmount": "0.00",
            "updatedDate": null
        }
    ]
}

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.

bash
curl -X PUT {baseUrl}/v1/virtualibans/{virtualIbanId} \
	--header 'Authorization: Bearer {accessToken}' \
	-d '{
		"validTo":"" // The expiration date (YYYY-MM-DD)
	}'

Returns the updated Virtual IBAN object.

json
{
    "virtualibans": [
        {
            "virtualibanId": 123456,
            "walletId": 0123456,
            "typeId": 2,
            "tag": "Test vIBAN",
            "reference": "",
            "validFrom": "2024-01-31",
            "validTo": null,
            "maxUsage": 10,		
            "maxAmount": "0.00",	
            "iban": "FR761679800001100000123455678",
            "createdDate": "2024-01-31 09:28:06",
            "numberOfTransactions": 0,
            "cumulatedAmount": "0.00",
            "updatedDate": null
        }
    ]
}

Endpoints ​

EndpointScope
/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