Banking - Account fees
Jump to navigation
Jump to search
Description
Account fees are charged either automatically or manually over accounts of a given account type. They need to be enabled in the product, so users with those accounts are charged. Each fee execution is logged, and can be monitored while being charged. Additionally, it is possible to search for specific users which have been charged an account fee.
The account fees list is viewed as a tab in the user account type details page. See Banking - Account types.
Business rules
- An account fee is always related to an user account type (there is no sense for fees over system accounts).
- When an account fee is created and enabled they are not automatically charged to all users having this account type. They are only charged on users having this account fee enabled in at least one of their products.
- When a user has multiple products with a given account type, where one of them enables the fee and others don't, the fee is charged anyway.
- The account fee has a generated transfer type which is used for charges.
- Only users in either active or blocked statuses are charged. Disabled and removed users are not.
- An account fee can be either scheduled (configured to run every given time interval) or manual.
- It is possible to make a fee pay users instead of charging them. For example, it is possible to configure a monthly bonus for users.
- A free base can be (optionally) used to prevent users under a given balance to pay the fee.
- There are the following possible charge types:
- Fixed amount: charges a fixed amount, but only if the balance is above the free base (if used);
- Volume percentage (only on positive balances, over period since last execution): Charges a percentage over the positive average balance above the free base (free base is always used, assumed zero if none). Mostly used for interest payments at savings accounts and demurrages;
- Volume percentage (only on negative balances, over period since last execution): Charges a percentage over the negative average balance under the free base (free base is always used, assumed zero if none). Mostly used for interest payments on negative accounts for loans and so on;
- Balance percentage (only on positive balances): Charges a percentage over the current account balance minus the free base (if used). Only charged if the result is positive;
- Balance percentage (only on negative balances): Charges a percentage over the current account balance plus the free base (if used). The absolute value is used for the charge. Charged if the result is negative.
Volume-based charges
- For volume-based charges the average balance is used. It is calculated by getting the account balance at the end of each day for the entire period, dividing by the number of days in the period. It is always calculated over whole days.
- For example: if we have a volume percentage fee that runs every month. The fee will be calculated as follows. If the account had a balance of $100 at the beginning of the month, then at day 07 paid $50, then at day 10 received $20, and at day 25 paid $70. In this case, the average balance is ($100 * 6 days + $50 * 3 days + $70 * 15 days + $0 * 6 days) / 30 days = 60. So, for example, if the fee is 1%, the charged amount is $0.60.
- If on the same example the free base is 20, not zero, the calculations would be: ($80 * 6 days + $30 * 3 days + $50 * 15 days + $0 * 6 days) / 30 = 44. A fee of 1% would, in this case, result in $0.44.
- When the fee is charged manually it is takes the period since it was last charged and when it was never charged it will charge it since the beginning.
- For interest calculation on a savings account this method yields the same results as calculating the interest per business closing day and adding them afterwards. For more information see:
Scheduling account fees
There are 4 settings who are important for the scheduling:
- Charge once per x days/weeks/months, this is the period over which the fee is charged.
- If you enter "Charge once per 1 month(s)", the fee will charge every month, volume-based charges will be calculated over the calendar month (the first day of the month to the last day).
- If you enter "Charge once per 6 month(s)", the fee will charge every half year, volume-based charges will be calculated over the first day of the calendar month till last day of the calendar month 6 months later.
- If you enter "Charge once per 1 week(s)", the fee will charge every week. Cyclos always considers Sunday as the first day of the week. So, volume-based charges will refer to periods from Sunday to Saturday.
- If you enter "Charge once per 4 week(s)", the fee will charge every four weeks, volume-based charges will be calculated starting on Sundays till Mondays, 4 weeks later.
- If you enter "Charge once per 1 day(s)", the fee will charge each day, volume based charged will be charged over the closing balance of that day.
- If you enter "Charge once per 10 day(s)", the fee will charge every 10 days, volume based charged will be calculated over this period of 10 days (summing up the closing balances of those 10 days taking the average and calculating the percentage over this amount).
- Charge on (day), this is the day the fee will be charged and moved using the generated transfer type.
- When the period explained above ends this will be the day the fee will actually be charged. So for example if the fee is charged every month, and Charge on (day) 10 is set, then the fee will be charged the 10th of each month for the previous month.
- Charge on (hour), this is the hour the fee will be charged and moved using the generated transfer type.
- Please be aware that the fee won't run on the exact hour, Cyclos instead distributes the different services running over the hour, to prevent the system to have a very high workload at every whole hour. So the fee will run for example at 12.19 instead of 12.00. Or any other random time after twelve. Without restarting the server the next charges will likely run in the same minutes, but it is not guaranteed.
- First charged period starts at, this is the date the fee starts running.
- Volume-based charges will work a bit different, and for the first charge the charge is calculated for a different period (from this date till the end of the period), this is easiest explained with a couple of examples:
- E.g. if you enter "Charge once per 1 month(s)" and set the "First charged period starts at" to 15th of January. Then the first volume-based fee will be calculated over the days 15th of January to the 31st of January. And only afterwards the fee will be calculated over the period from the first to the last day of the month.
- E.g. if you enter "Charge once per 1 week(s)" and set the "First charged period starts at" to 18th of January 2022 (which is a Tuesday). Then the first time the fee will run it will only charge from 18th of January (Tuesday) till 22th of January (Saturday). Subsequent charges will be from Sunday to Saturday.
- Fixed amounts and balance percentages, on the other hand, don't charge over a reference period. So, regardless if the first charge was a partial or full period, the amount won't be impacted. Fixed amounts are fixed, and balance percentages use the balance at the moment the fee is calculated.
- E.g. in this case if you enter "Charge once per 1 month(s)" and set the "First charged period starts at" to 15th of January and Charge on (day) to the 16th. Then the 16th of January it will run the first charge. This will be a fixed amount or a percentage over the account balance the users have at their account at the time of the charge.
- Volume-based charges will work a bit different, and for the first charge the charge is calculated for a different period (from this date till the end of the period), this is easiest explained with a couple of examples:
Pages
Account fee list & create new
The account fee list is can be accessed from within a member account details configuration page (in the most right tab)
Note: This the list that shows the current account fees, and an option to create a new one. For the a list of the operational account fees (status on running etc.) can be found in the 'Accounts fees overview' page (directly below)
New
| Fields | Type | Rules |
| New | Action button | Create a new account fee type
|
List
* Automatically shows all transfer type authorization levels specified for the transfer type, sorted on level.
| Fields | Type | Rules |
| Name | Text | Name of the account fee |
| Enabled | Boolean | |
| Amount | Integer | Configured charged amount of the fee |
| Charge once per | Period | |
| Charge on day | Date | |
| Charge on hour | Date time |
Account fee details (configuration)
The account fee details page can be accessed from within a member account details configuration page (in the most right tab) and selecting an account fee from the list, or create a new one with the New button.
| Fields | Type | Rules |
| Name | Text | Name of the account fee.
|
| Internal ame | Text | |
| Description | Text area | Description of the account fee. |
Enabled
|
Boolean |
Checkbox to enable the fee.
|
Notify when success
|
Boolean | When selected it will send a system alert for failed and successful account fees |
Charge mode
|
Single selection |
Determines how the fee is charged.
|
Balance handling
|
Single selection |
Determines which balance situation should be considered or not at chargin the account fee.
|
Payment direction
|
Single selection |
Determines if users pay to or get paid by a system account.
|
Generated transfer type
|
Single selection |
Defines the transfer type for generated transfers of this fee
|
| Amount | Percentage or currency |
Determines how to calculate the amount which should be charged as fee.
|
Calculation script
|
Single selection |
Sets the custom script used for calculating the fee amount
|
Script parameters
|
Text area |
Parameters passed to the calculation script. The parameters are parsed as a Java Properties (see the expected format)
|
Free base
|
Currency amount |
The free base used for calculations. See #Business rules.
|
Run mode
|
Single selection |
Determines whether the fee runs at fixed intervals or manually
|
Charge once per
|
Time interval |
Determines the fee recurrence.
|
Charge on (day)
|
Single select |
Determines the day the fee is expected to be charged.
|
Charge on (hour)
|
Single select |
Hour of day when the fee is charged: 12.00 AM - 11.00 PM.
|
First charged period starts at
|
Date |
Determines the first date to start charging the fee.
|
Account fees overview
This page is available from the system banking menu - Account fees
Search (filters)
| Fields | Type | Rules |
Currency
|
Single selection |
|
Name
|
Text | |
Show disabled
|
Boolean | Shows also the account fees that do not have the 'enabled' check box selected. |
Search
|
Action |
Search result (list)
- Automatically shows all account fees of all visible user account types by the logged admin, sorted by account type name and account fee name.
- Clicking on a row shows the Account fee history page.
| Fields | Type | Rules |
Account type
|
Text | Name of the account type. |
Account fee
|
Text | Name of the account fee.
|
Amount
|
Text | Shows the charged amount (either formatted as currency if the account fee charge mode is fixed amount or as percentage otherwise) |
Last execution
|
Text | Shows the last execution date if the last execution has finished. Otherwise, shows the last execution status. |
Next execution
|
Text | Shows the next expected execution date if the fee is scheduled, or the label 'Manual' if the fee is manual. |
| Row | Action | Navigate to "Account fee history" |
Account fee history
The account history of a fee is shown when a fee has been selected in the Account fee overview list page (see above).
Search page (filters)
| Fields | Type | Rules |
| Status form | ||
| Account type | Text label | |
| Account fee | Text label | |
| Amount | Currency amount label | Amount of the fee |
| Next Execution | Date label | |
| Products | Text label | Products that have the fee enabled |
| Filters | ||
| Period | Date period | Filters by account fee execution date |
| Run now | Action button | Allows starting a new charge (manual fee only). When clicking on the "Run now" button, will take the user to the Account fee execution details page for the new execution.
|
| Search | Action button | |
Search result (list)
Automatically shows the first page of previous executions for the currently selected account fee, ordered by date descending.
If there are any failed users, show the row as red.
Clicking on a row shows the Account fee execution details page for the selected execution
| Fields | Type | Rules |
| Date | Text | The date the execution is expected to run (when scheduled) or when was actually started (manual) |
| Period | Text | Shows the days over which the fee was charged
|
| Amount | Text | Shows the charged amount (either formatted as currency if the account fee charge mode is fixed amount or as percentage otherwise) at the moment the fee was executed (it could have changed on the fee definition afterwards) |
| Free base | Text | Shows the fee base at the moment the fee was executed (it could have changed on the fee definition afterwards) |
| Status | Text | Shows the execution status. See more details in the account fee execution details page specification |
| Row | Action | Navigate to "Account fee execution details" |
Account fee execution details
The account fee execution details are shown when clicking on a row in the account fee history list page (see above).
- Shows details for a particular account fee execution.
- If there are failed users and the execution is finished, allows attempting recharging them.
- If the current execution is running (or recharging failed users), the page will keep refreshing, every few seconds, to update the statistics.
| Fields | Type | Rules |
| Date | Date label | The execution date |
Status
|
Text label |
The execution status.
|
| Period | Period label | The charged period, in whole days
|
| Amount | Currency amount label or percent label | The charged amount (either currency value if the fee is fixed, or percentage) |
| Free base | Currency amount label | The free base at the moment of the charge, if used. (for an explanation of the free base see the business rules at the top of the wiki) |
| Total charged amount | Currency amount label | The sum of all generated transfers amounts
|
| Users pending | Integer | The number of users currently pending to be processed |
Failed users
|
Integer | The number of users where the charging failed (for example, not enough balance)
|
| Skipped users | Integer | The number of users which were not charged because the amount to be charged was zero (i.e., didn't generated a transfer for them) |
| Charged users | Integer | The number of users which were effectively charged (i.e., a transfer was generated for each of them) |
| Total users | Integer | The total number of users affected by the fee.
|
| Acctions | ||
| Recharge failed users | Action button |
|
Events log (result list)
Displays the event log for the selected execution
| Fields | Type | Rules |
| Date | Text | The event date |
| Type | Text | The event type.
Possible values:
|
| By | Profile link | The administrator that started the fee (when available) |
Charged users tab
Charged users search (filters)
| Fields | Type | Rules |
| Status | Multi selection | Allows selecting the status for users within this fee execution
|
| Group | Multi selection | Allows selecting the group for charged users, in a hierarchical fashion |
| User | User selection | Allows searching & selecting a specific user |
Charged users result (result)
Automatically shows the first page of users processed on this account fee execution
Clicking a row will lead to the selected user profile. See Users - Users
| Fields | Type | Rules |
User
|
Profile link | The affected user |
| Status | Text or Link | The user status in this charge, if status is Failed it show the error on click |
| Amount | Currency amount text | The charged amount for the given user |
| Row | Action | Navigate to the user profile |