Account hierarchy
Account hierarchies allow you to create a hierarchical structure of your corporate customer accounts. The hierarchy can be set by e.g. per department, geographical area or business area. The hierarchy allows you to establish links between your customer’s accounts.
This feature is applicable to credit and prepaid products. The hierarchy always consists of one top account and under the top account, you can establish multiple sub accounts. There can even be multiple levels within the hierarchy, i.e. a sub account under a sub account. Cards are always linked to a sub account.
Key benefits of creating an account hierarchy
- Control the spend of the entire hierarchy by setting a credit limit on the top account. This will allow for setups where even though there are multiple accounts, they can’t jointly exceed a predefined shared limit.
- Set spend controls that apply to the entire hierarchy. Spend controls set on the top account level (e.g. ATM withdrawal limit) will apply to all accounts and cards in the hierarchy which is an effective way to control specific spend.
- With the link between the accounts, it is very easy to block and close all accounts and cards in the hierarchy. This removes the need to close each separate account if the customer e.g. defaults.
- Effortlessly keep track of the total prepaid balance in a hierarchy of prepaid accounts.
- The links in the hierarchy are available in Enfuce interfaces and allow a simple way to visualise the hierarchy for customers in customer facing interfaces.
Defining available amount in a credit account hierarchy
An account hierarchy consists of one top account and connected sub accounts. The top account will be the account that controls the overall available amount for the whole hierarchy, meaning that the sub accounts cannot exceed the top account’s, i.e. the entire hierarchy’s available amount.
When an authorisation is received on a sub account level, the system checks both the sub account’s and the top account’s available amount and makes the decision to either approve or to decline the transaction.
If the top account or the sub account don’t have enough available amount, the authorisation will be declined. In other words, both the top account and the sub account need to have enough available amount in order for the authorisation to be approved.
Credit limits in an account hierarchy
Both the top account and the sub accounts can have their own credit limits. The sub account’s accumulated credit limits can be more than the top account’s credit limit, but the top account’s available amount will limit the usage in cases where a sub account has a higher available amount than the top account.
Use case description for credit limits in an account hierarchy
- £15.000 credit limit is set to a corporate top account
- This will allow yourself and your customer to control the usage of the entire hierarchy. The credit limit can be updated via ‘Account API update’ call to the top account.
- Your customer wants to define department specific limits. In this example, the sum of the sub account’s credit limit £18.000 exceeds the top account’s credit limit of £15.000. But from the usage perspective, the sub account’s joint spend can’t go over the top account’s credit limit. The top account will always control the balance of the sub accounts
- Department 1 makes a £10.000 purchase
- Department 3 makes a £5.000 purchase
- Department 2 tries to make a £1000 purchase but it is declined as the total spend is already £15.000.
Invoicing and incoming payments in an account hierarchy
Each sub account is invoiced separately and payments are posted to a specific sub account. A payment will increase the available amount for the respective sub account as well as increase the available amount on the top account level. Payments to sub accounts will not impact the other sub accounts’ balance or available amount.
Use case example:
- Starting point:
-
- Department 1 has a total balance of £6000, available amount £4000.
- Department 2 has a total balance of £3000, available amount £0.
- Department 3 has a total balance of £2500, available amount £2500.→ top account available amount is £3500 (=15.000£ (£6000 + £3000 + £2500)).
-
- Department 1 makes a payment of 5000£.
-
- Department 1 total balance will be reduced to £1000 (£6000 – £5000), and available amount increased from £4000 to £9000.
- The available amount of the top account will increase from £3500 to £8500 (as per the £5000 payment). Note that the available amount of the top account will also limit Department 1 using no more than £8500.
- The available amount of Department 2 (£0) and Department 3 (£2500) will remain the same.
-
Invoicing on the sub account level enables sub account specific settings such as due date and payment terms set per each sub account.
Defining the available amount in a prepaid account hierarchy
For prepaid products, the top account reflects the sum of available amounts for all sub accounts. For example, when posting a top-up transaction to the sub account, it is reflected in both the sub account’s and the top account’s available amount.
Unlike a credit setup, the top account in a prepaid account hierarchy only reflects the total amount of prepaid balance of the sub accounts. By default, the top account doesn’t limit the spend of sub accounts, i.e. the sub accounts available amount is the sole defining factor for available amount.
When an authorisation is received on a sub account level, the available amount of the sub account will determine if the authorisation can be approved or not. The reason for this is that in a prepaid setup the top account available amount is always the same or more than the available amount of the sub account.
Spend on the sub accounts in a prepaid account hierarchy can be controlled with spend controls on top account level which are explained in the next section.
Spend controls in an account hierarchy
The spend control functionality is the same regardless if the accounts are credit or prepaid products. Spend controls set for the top account apply to all connected sub accounts and will override even if a sub account has more available balance than the top account.
Use case description for spend controls in an account hierarchy
- Top account ATM withdrawal spend control: £500/day
- Sub account ATM withdrawal spend control: £300/day
- Sub account A makes a £300 withdrawal → Top account spend control updated to £200 ATM withdrawals left for the day
- Sub account B tries to make a £250 ATM withdrawal (which is within sub account B’s spend control limits)
- The withdrawal is declined as the top account spend control’s only allow for £200 to be withdrawn
Closing and blocking accounts in an account hierarchy
If the top account is set to ‘Account Blocked’, this will result in a decline for all authorisations attempted by any of the accounts or cards in the hierarchy. The ‘Account Blocked’ status will, however, not result in the change of status on the sub accounts or cards linked to them.
If the top account is closed by setting to ‘Account To Close’, the linked sub accounts will also receive the same account status and the connected cards will be set as ‘Card Blocked’. The closing process will continue for the accounts and cards in the hierarchy as per standard closing process.
Please note that in case you want to stop the account closure process and re-open all the accounts and cards, you will need to update all accounts and cards separately to ‘Account/Card OK’ status. In other words, opening the top account will not automatically re-open all the connected sub accounts and cards.
Each sub account can be closed individually as well. If a single sub account’s status is updated to ‘Account Blocked’ or ‘Account to Close’, it will only apply to that sub account and will not impact other sub accounts or top account in the hierarchy.
Relevant API calls for account hierarchy
Create an account hierarchy
First start by creating the credit account for the top account.
Use the API call: POST /v4/CREDIT/customer/{customerId} *
*choose appropriate endpoint depending on the product
Example Payload 1
{
"creditLimit": 10000,
"productCode": "CREDIT_EUR_FI"
}
Then create the sub account for the top account by using the same API POST /v4/CREDIT/customer/{customerId} *
Now in the payload, include the field parentId
and add in that field the top account id, received from the previous call. Here in the API the parentId
= top account Id.
Example Payload 2
{
"parentId": 9876543210,
"creditLimit": 10000,
"productCode": "CREDIT_EUR_FI"
}
Now you have created a top account and a sub account. You can continue to create multiple sub accounts under that specific top account id (parentId
). After you have created the accounts, you can proceed to create the cards. Make sure you use the sub account id when creating the card.
Note that all accounts in the hierarchy have to be for the same product (same productCode).
‘Get Account’ hierarchy details
To get account details for the whole hierarchy, you can use below GET call:
GET /v4/subAccount/{accountId}
In the accountId
enter the top account ID.
Below GET calls can still be used to fetch information for single sub accounts:
GET /v4/accountNumber/{accountNumber}
GET /v4/customer/{customerId}
GET /v4/{id}
Update the linked top account
Sub accounts can be moved between top accounts (by changing the parent id for the sub account). To update the top account use the appropriate API call:
PATCH/v4/CREDIT/{id}
PATCH/v4/PREPAID/{id}
PATCH/v4/FLEET/{id}
Example Payload
{
"parentId": 9876543210
}
Enfuce data export files
Account files
In the account files, we populate all accounts both top accounts and sub accounts. Top accounts are called “parent accounts’ in the data export files. Sub accounts have their connected top account ID and a contract number in the following fields:
- PARENT_ACCOUNT_ID
- PARENT_CONTRACT_NUMBER