Appearance

IBAN ​

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

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

Treezor offers 2 IBAN-related services:

IBAN features are compatible with transfers as follows:

TransferVirtual IBANLocal IBAN
Received SEPA Direct Debit (SDDR)yes checkmarkyes checkmark
Emitted SEPA Direct Debit (SDDE)no crossyes checkmark
Received SEPA Credit Transfer (SCTR)yes checkmarkyes checkmark
Emitted SEPA Credit Transfer (SCTE)no crossyes checkmark
Received SEPA Instant Credit Transferyes checkmarkyes checkmark
Emitted SEPA Instant Credit Transferno crossyes checkmark
Wallet-to-Walletno crossno cross

Virtual IBAN ​

You can Virtual IBANs to a Wallet besides the automatically assigned IBAN. There is no limitation on the number of Virtual IBANs per Wallet.

Toolbox icon

Feature subscription required

Please reach out to your Treezor Account Manager to learn more about the conditions for using this service.

Use cases ​

Virtual IBAN offers capabilities and restrictions that are not available with the Wallet main IBAN. Therefore, they allow for a more granular handling of operations.

CapabilityBenefits
Usage restrictionRestricting the usage of a Virtual IBAN to specific users or usage allows you to better categorize funds movements.
Virtual IBAN deactivationDeactivating the Virtual IBAN without closing the Wallet facilitates of litigation handling, for instance.

Virtual IBANs include operation limitations to prevent abuses:

  • Single direction – Support either outgoing (SDDR) or incoming (SCTR) funds.
  • Timeframe – Limit a Virtual IBAN usage between two specified dates.
  • Number of transaction – Set a maximum number of transactions for a Virtual IBAN.
  • Maximum amount – Set a maximum cumulated amount for a 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 (number)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.

To create a Virtual IBAN, use the following request:

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.

Although the validTo date can't be set in the past, you can update it to be in the near-future by using the /v1/virtualibans/{virtualIbanId} 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

Local IBAN ​

Bank accounts are country-specific, which is reflected by the first 2 characters of the IBAN (country code). You can create accounts with a BIC and IBAN based in the user’s distributionCountry.

Gear icon

Configuration – Environment configuration by Treezor

Please contact Treezor to set up your distribution countries and available IBANs per country. Required fields upon creating a Wallet change depending on your setup.

Local IBANs are compatible with all Treezor transaction flows.

In the specific case of Wallet-to-Wallet transfers, transfers are only possible when the wallets have IBANs of the same country. Otherwise, you need to make a SEPA Credit Transfer instead.

Available countries (bic) ​

While by default, Treezor provides French IBAN, the following countries are available: Germany, Italy, and Spain.

Find below the available bic values structure per country. These BICs are to be adapted depending on the value Treezor provided you.

Country codebic structure
FRTRZOFR21XXX
DETRZODEB2XXX
ITTRZOITM2XXX
ESTRZOESM2XXX

Creating a Local IBAN ​

Treezor generates the IBAN when creating a Wallet. Depending on your configuration, you may specify the location of the IBAN by either:

  • Relying on the distributionCountry of the wallet owner
  • Specifying the bic value

In most cases, however, the bic country must be aligned with wallet owner's distributionCountry.

Parameters ​

Below are the main parameters to create a wallet with a local IBAN.

AttributeTypeDescription
tariffId integerThe fees applied to the Wallet, as defined by your contract with Treezor. Usually required, but may have a default value set by Treezor.
walletTypeId integerThe type of Wallet. Allowed values are:
  • 9 – Electronic Money Wallet
  • 10– Payment Account Wallet
bic stringThe country in which the wallet is domiciled.
The BIC is required depending on your configuration; it can default to the configured value only if there is only one allowed bic value authorized for a given distributionCountry. Contact Treezor for more information about your configuration.
userId integerThe unique identifier of the User who owns the Wallet.
currency stringThe currency of the Wallet. Can only be EUR.
eventName stringThe name of the Wallet.
code icon

API – API Reference available

For a complete list of Wallet attributes, check the Wallets section of the API Reference.

Request example ​

Here is the request to create a Wallet:

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

Here is an example of {payload}:

json
{
	"walletTypeId":10,
	"bic":"TRZODEB2XXX",
	"tariffId":{tariffId},
	"userId":123456,
	"currency":"EUR",
	"eventName":"Wallet DE"
}

Returns the Wallet object with the BIC and IBAN localized in the desired country.

json
{
    "wallets": [
        {
            "walletId": 3445765,
            "walletTypeId": 10,
            "walletStatus": "VALIDATED",
            "codeStatus": 120005,
            "informationStatus": "",
            "walletTag": "",
            "userId": 100962903,
            "userLastname": "Oak",
            "userFirstname": "Alex",
            "jointUserId": 0,
            "tariffId": 136,
            "eventName": "Wallet DE",
            "eventAlias": "wallet-de-67093a222d23a",
            "eventDate": "2024-10-18",
            "eventMessage": "",
            "eventPayinStartDate": "2024-10-11",
            "eventPayinEndDate": "0000-00-00",
            "contractSigned": 0,
            "bic": "TRZODEB2XXX",
            "iban": "DE72100102000003445765",
            "urlImage": "",
            "currency": "EUR",
            "createdDate": "2024-10-11 16:45:54",
            "modifiedDate": "0000-00-00 00:00:00",
            "payinCount": 0,
            "payoutCount": 0,
            "transferCount": 0,
            "solde": 0,
            "authorizedBalance": 0,
            "totalRows": 1,
            "country": "FR"
        }
    ]
}