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 fundsSCT
. - 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 – 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:
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
}
]
}
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
Endpoint | 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 |