Interest Rate Management Enhancements

Interest rate changes based on the value Dates

Interest rates serve as tools for financial institutions to respond to economic shifts, stay competitive locally and globally, and attract new customers. IFRS 9, an accounting standard by the International Accounting Standards Board (IASB) guides the recognition, measurement, and presentation of financial instruments. Under IFRS 9, changes in interest rates on savings accounts generally don't retroactively affect interest income. Instead, interest income is calculated using the effective interest rate method, based on the instrument's initial carrying amount and the effective interest rate at inception. Changes in rates affect future interest income calculations, applied prospectively from the effective date of the rate change.

When changes in interest rates occur, Mambu currently recalculates interest accruals to the last interest payment. This deviates from the principles of IFRS 9 and restricts the flexibility in interest applications.

As a response, we have re-designed the interest rate management for savings products in 2023. This page addresses the re-design principles and provides guidelines for users of the Mambu platform to seamlessly execute interest rate changes.

Terminology

Interest availability: Every interest configuration is now (after migration and enablement) associated with an interest availability record which indicates when this interest configuration becomes effective on the account. It is stored on the account level and represents interest rate change history for each account.

interestAvailabilityKey: The unique identifier for each interest availability record.

type: In Mambu Deposits engine there are 3 types of interest; Regular, Overdraft and Technical Overdraft. In more general terms those can be thought of as credit interest, arranged overdraft interest and unarranged borrowing/overdraft interest. Within this new capability, we are enabling changes to the Regular type of interest. Overdraft and Technical Overdraft are to follow in 2024.

startDate: This is the value date that you would need to set when creating or updating an interest availability record. It is the “effective from” indicator for interest availability.

Product propagation: In the Mambu platform, every account created under a product inherits all configuration parameters from the product. Hence the product is considered as a template that defines product specifics to be used by deposit accounts. When changing a product configuration parameter, depending on the parameter, the user is asked if the new value is applicable to all existing (already created) accounts and new accounts or only to new accounts. If the existing accounts option is chosen this means that for Mambu to pass down the new value of the parameter to all accounts under that product, the process of updating the parameter value is completed via Cron Jobs (as part of EOD process), although the change is reflected in Mambu UI immediately at the account level. This routine is called product propagation.

Bulk processing: This describes the technical process of executing one request that has several tasks in it. It works with a queuing mechanism where every record is processed one after another and the processing status can be tracked when needed. An example of this already exists, see: https://api.mambu.com/#deposit-transactions-makebulkdeposits

Live migration: This is an inhouse solution that Mambu uses when there is a need for an update on the data structure due to accommodate a new implementation. This solution does not require any down time and can be repeated if it fails for any reason. Also live migration guarantees data integrity.

What changes from the existing functionality?

Upon the start of the live migration, the following existing functionalities will be disabled:

• POST /deposits/{depositAccountId}:changeInterestRate endpoint
• POST /depositproducts/{depositProductId}:batchUpdate
• Interest rate changes for All Existing Accounts, on the Edit Product page via Mambu UI

The disablement will take effect right before the start and will become permanent when the live migration is completed successfully. After the live migration is complete, the new endpoints will be enabled and the new functionality will become ready for use.

What are the components of the new functionality?

Create Interest Availability for an Account

Endpoint: POST /deposits/{depositAccountId}/interest-availabilities
Every account will automatically be associated with an interest availability record from the activation date of the account in the new solution. This interest availability will define which interest rate is effective for an account on a certain date. When a Mambu user needs to change the interest rate on an account they will be using this endpoint. They will be required to supply account id, start date, interest type and an interest rate in the payload. Only the regular interest will be recognised, which should be specified by “type”: INTEREST in the request.

Rules and validations on this endpoint:

• Permissions required: EDIT_SAVINGS_ACCOUNT
• Account states that are allowed: PENDING_APPROVAL, APPROVED, ACTIVE, ACTIVE_IN_ARREARS, DORMANT, LOCKED
• For accounts in DORMANT or LOCKED states, the only available option is to create an interest availability with a future date.
• For accounts in PENDING_APPROVAL, APPROVED states, the interest availability will become effective upon account activation.
• For accounts in DORMANT state, the interest availability will become effective when the account becomes ACTIVE again. Once the account returns into ACTIVE state, interest will be accrued (and applied if interest application date is involved) with the interest availability that was effective for the dormancy period.
• For accounts in LOCKED state, the interest availability will become effective upon unlocking the account and the account will be appraised to the point of locking date with the effective interest rate.
• Interest rate terms that are allowed: FIXED, TIERED BY BALANCE, TIERED BY BANDS, TIERED BY PERIOD:
  • For the FIXED interest rate term, there are 2 interest rate source options available, Fixed or Indexed.
  • For fixed rates, the interest rate can be changed as expected.
  • For indexed rates, changing the Spread Default value will be possible in the upcoming releases, as of now it is restricted. Spread Min and Spread Max values will keep respecting the product configuration. Index Source itself can be managed at Admin level.
  • For the TIERED BY BALANCE, the interest rate can be changed as expected.
  • For the TIERED BY BANDS, the interest rate can be changed as expected.
  • For the TIERED BY PERIOD interest rate term, the start date can only be the current date, this interest rate term does not allow backdating or future dating an interest availability.
• Negative rates will be only allowed if the product configuration allows negative interest.

Use case 1:
An interest rate availability created with a past date triggers backdated transactions. Mambu will follow the existing backdating process.

E.g. An example account setup for illustration:

Assuming that this account has only one interest availability record as:

If there is an interest rate change activity via the POST /deposits/A/interest-availabilities endpoint on 15.01.2024 with the following request body:

{
 "type": "INTEREST",
 "startDate": "2024-01-05",
 "interestRateSettings": {
   "interestRate": 2.89
 }

Then when this request is processed successfully, the interest accrual between 05.01.2024 and 15.01.2024 will be recalculated using the interest rate of 2.89%. From 15.01.2024 the account will keep accruing interest with the rate of 2.89% This will be reflected in the account immediately.

Interest Accrual calculation with the EOD that starts at 00:00 on 16.01.2024:
Accrued Interest Amount = [((05.01.2024 - 01.01.2024)/365)x(2.67%)x(Account Balance)] + [((16.01.2024 - 05.01.2024)/365)x(2.89%)x(Account Balance)]

Use case 2:
An interest rate availability created with a future date will be stored immediately, and it will be recognised by a new job that will run after every EOD upon arrival of the future date.

E.g. Same example account setup from the previous point:

For this account there are now 2 interest availability records as:

If there is an interest rate change activity via the POST /deposits/A/interest-availabilities endpoint on 16.01.2024 with the following request body:

{
 "type": "INTEREST",
 "startDate": "2024-01-18",
 "interestRateSettings": {
   "interestRate": 2.68
 }

Then when this request is processed successfully, an interest rate change transaction will be logged on the account with the date of 18.01.2024 and the new rate will be picked up by a new cron step on 18.01.2024 at midnight and will be become the effective rate for the account appraisal step of the EOD that starts at 00:00 on 19.01.2024 at 00:00 (assuming the EOD starts at midnight).

Interest Accrual calculation with the EOD that starts at 00:00 on 19.01.2024:
Accrued Interest Amount = [((05.01.2024 - 01.01.2024)/365)x(2.67%)x(Account Balance)] + [((18.01.2024 - 05.01.2024)/365)x(2.89%)x(Account Balance)] + [((19.01.2024 - 18.01.2024)/365)x(2.68%)x(Account Balance)]

Use case 3:
An interest rate availability created with the current date as a start date, it will be stored immediately, and it will be recognised by the account appraisal process at the EOD.
E.g. For the same example account:

For this account there are now 3 interest availability records as:

If there is an interest rate change activity via the POST /deposits/A/interest-availabilities endpoint on 19.01.2024 with the following request body:

{
 "type": "INTEREST",
 "startDate": "2024-01-19",
 "interestRateSettings": {
   "interestRate": 3
 }

Then when this request is processed successfully, an interest rate change transaction will be logged on the account on date 19.01.2024 at the time of request, and the new rate will be used by the next cron that starts at 00:00 on 20.01.2024 (assuming the EOD starts at midnight).

Interest Accrual calculation with the EOD that starts at 00:00 on 20.01.2024:
Accrued Interest Amount = [((05.01.2024 - 01.01.2024)/365)x(2.67%)x(Account Balance)] + [((18.01.2024 - 05.01.2024)/365)x(2.89%)x(Account Balance)] + [((19.01.2024 - 18.01.2024)/365)x(2.68%)x(Account Balance)] + [((20.01.2024 - 19.01.2024)/365)x(3%)x(Account Balance)]

Update Interest Availability for an Account

Endpoint: PUT /deposits/{depositAccountId}/interest-availabilities/{interestAvailabilityKey}
This endpoint will allow users to make corrections or changes on an existing interest availability.

Rules and validations on this endpoint:

• Permissions required: EDIT_SAVINGS_ACCOUNT
• This endpoint respects all validations listed for POST /deposits/{depositAccountId}/interest-availabilities.
• Start date is not allowed for updating.
• Type parameter is not allowed for updating.
• Based on the start date that is on the interest availability record, this endpoint may trigger recalculation of interest.

E.g. Same example account from the previous point:

Updating the IA xxx2:
In case of an interest rate change activity via the PUT /deposits/A/interest-availabilities/xxx2 endpoint on 20.01.2024 with the following request body:

{
 "interestRateSettings": {
   "interestRate": 3.01
 }
}

Then when this request is processed successfully, the interest accrual between 19.01.2024 and 20.01.2024 will be recalculated using the interest rate of 3.01% instead of 3%. From 20.01.2024 the account will keep accruing interest with the rate of 3.01% This will be reflected in the account immediately.

Recalculation of interest accrual  triggered on 20.01.2024:
Accrued Interest Amount = [((05.01.2024 - 01.01.2024)/365)x(2.67%)x(Account Balance)] + [((18.01.2024 - 05.01.2024)/365)x(2.89%)x(Account Balance)] + [((19.01.2024 - 18.01.2024)/365)x(2.68%)x(Account Balance)] + [((20.01.2024 - 19.01.2024)/365)x(3.01%)x(Account Balance)]

Interest Accrual calculation with the EOD that starts at 00:00 on 21.01.2024:
Accrued Interest Amount = [((05.01.2024 - 01.01.2024)/365)x2.67%)x(Account Balance)] + [((18.01.2024 - 05.01.2024)/365)x(2.89%)x(Account Balance)] + [((19.01.2024 - 18.01.2024)/365)x(2.68%)x(Account Balance)] + [((20.01.2024 - 19.01.2024)/365)x(3.01%)x(Account Balance)] + [((21.01.2024 - 20.01.2024)/365)x(3.01%)x(Account Balance)]

Get Interest Availability with Interest Availability Id for an Account

Endpoint: GET /deposits/{depositAccountId}/interest-availabilities/{interestAvailabilityKey}
This endpoint can be used for retrieving a specific interest availability record for an account.

Rules and validations on this endpoint:

• Permissions required: VIEW_SAVINGS_ACCOUNT_DETAILS

Get Interest Availability for an Account

Endpoint:GET//deposits/{depositAccountId}/interest-availabilities?paginationDetails=OFF&type=INTEREST&from=2024-02-01&to=2024-02-04
This endpoint can be used for retrieving interest availability records for an account and allows filtering by interest type and/or date range.

Rules and validations on this endpoint:

• Permissions required: VIEW_SAVINGS_ACCOUNT_DETAILS

Delete an Interest Availability for an Account

Endpoint:DELETE/deposits/{depositAccountId}/interest-availabilities/{interestAvailabilityKey}
This endpoint can be used when there is a need to remove an interest availability record from an account.

Rules and validations on this endpoint:

• Permissions required: EDIT_SAVINGS_ACCOUNT
• Every interest availability record can be deleted except from the first (oldest) record on the account.
• Deleting an interest availability can trigger recalculation of the interest.

Bulk Update Interest Availabilities for Existing Accounts

Endpoint: POST /deposits/interest-availabilities:bulk
This endpoint is the enhanced version of product propagation action. Now with this implementation it becomes possible to apply an interest rate change to a sub-set of accounts. It is also possible to apply the changes to all existing accounts under the same product.

Rules and validations on this endpoint:

• Permissions required: MAKE_BULK_CHANGE_INTEREST_AVAILABILITY
• This endpoint concludes 2 input parameters under “accountFilter” wrapper as;
• “productId” or encodedKey of the product
• “Ids”or the encodedKeys of the accounts
• Product id and Ids cannot be used at the same request.
• Providing a product id will mean that changes posted in the request will be applied to all existing accounts under this product.
• For using Ids at least one account id is required to be provided.
• When using Ids, the maximum number of account ids that can be provided is 100.000 (configurable) due to RESTful API constraints.
• The following interest configuration parameters can be changed with this endpoint:
  • interestRate
  • interestSpread*
  • interestRateTiers
  • Interest Charge Frequency

Bulk processing details

• The endpoint works asynchronously, after an initial validation of the payload work is scheduled to be executed on the background workers.
• In case of a success scheduling an identifier is being returned that can be used for tracking the progress & results of the asynchronous operation by using the endpoint /api/bulks/{identifier}.

Sample result from calling /api/bulks/{identifier};

{
   "status": "ERROR", <<– this is an overall status, if at least one error occurred
   "errors": [
       {
           "indexInRequest": 0, <<– always 0 in bulk Interest Availabilities case
           "externalId": "33",   <<– the id/encoedkey of the account
           "errorSource": "An InterestAvailability already exists for account with the same date and type.",   <<- error related information ->>
           "errorCode": 8104,
           "errorReason": "INVALID_INTEREST_RATE_SETTINGS"
       },
       {
           "indexInRequest": 0,
           "externalId": "34",
           "errorSource": "An InterestAvailability already exists for account with the same date and type.",
           "errorCode": 8104,
           "errorReason": "INVALID_INTEREST_RATE_SETTINGS"
       }
   ],  <<- all successful processings appear below ->>
   "processedItems": [{
           "indexInRequest": 0,
           "externalId": "17"
       },
       {
           "indexInRequest": 0,
           "externalId": "29"
       },
]
}

A bulk interest availability change process that is interrogated via /api/bulks/{identifier} can be in one of the following states:

Only when the process reaches ERROR or COMPLETE stage full response is available.

E.g. Use Case: A new interest rate availability created for all existing accounts under the same product, with a current date as the start date. This action can be executed in 2 different ways;

• By providing the Product Id in the request of POST /deposits/interest-availabilities:bulk endpoint.
• By providing the list of Account Ids in the the request of POST /deposits/interest-availabilities:bulk endpoint.

In which case, Mambu will retrieve all accounts that are linked to the product id provided or the account ids provided in the request and post the new interest availability record to each one of those accounts, create an interest rate change transaction for every account retrieved and the next EOD will update the interest rate used for account appraisal.

Request body sample:

{
 "accountFilter": {
   "productId": "product1"
 },
 "interestAvailability": {
   "type": "INTEREST",
   "startDate": "2024-01-26",
   "interestRateSettings": {
     "interestRate": 4.2
         }
 }
}

Comparison between the old and new solution

What actions will you need to take?

For accommodating these changes Mambu will execute a live migration based on the process described below:

1. We will be migrating tenants in batches based on batching by tenant environment, where practical to do so.
2. We will be migrating the first sandbox for each customer prior to migrating the production environment. With the exception of a few customers who do not run sandboxes, we have assumed a sandbox/production pair relationship. If a customer has more than one production environment, we have assumed that this will be treated in its own right; alongside its sandbox pair, i.e. another testing period per pair, in parallel in the majority of cases.
3. Mambu has made a determination of which customer sandbox should be designated as 'first', but of course this choice is entirely up to each customer.
4. We will allow a period of 10 days for the customer to test the new capability, prior to commencing the migration on the production pair.
5. All 1st sandboxes (i.e. some customers have more than one sandbox), will be migrated first.
6. Followed by all production environments, including those who do not have sandboxes, after the specified testing window.
7. All remaining sandboxes will be migrated once the production ones have completed.
8. For informational purposes, we would like to make you aware that each tenant must be migrated independently of one another.
9. The migrations will be commenced, aligned to a specific release.
10. Once the migration of a tenant has completed, the new endpoints will be exposed. There may be a lag, (we are expecting no more than 1 day in most cases), between these two events.
11. It should also be noted that during the migration, for most tenants this will be no more than 1 day, in some cases it may be 2-3 days if you have a high volume of accounts, e.g. >4 million, you will not be able to use:
    1. The change interest rate API (Fixed Term Interest Only)
    2. The Product Propagation of an Interest Rate functionality - executed either through the UI or APIs
12. Once the migration has completed, you will not be able to use the above capabilities, because they are being replaced/enhanced with the new capability.

Steps for Readiness

• Mambu customers are expected to review the high level user guide and a set of JSON descriptions that are shared with them to identify changes required on their end.
• Mambu will start and complete the aforementioned migration of your database on the first sandbox, (if you have one), of your choosing. We will then allow a period of time for you to carry out testing. A prerequisite for this testing will be any development you deem necessary on your end to automate/call the new endpoints. Hence we are providing approximately three months notice prior to this first migration.
• Once the first sandbox has been successfully tested, Mambu will proceed to migrate your production environment. Please note that we appreciate that we have many customers who run several production environments. Mambu has made a determination to pair a ‘first sandbox’ with its accompanying production environment. I.e. to test and sign-off against, prior to migrating the production tenant. Where a second or tertiary production environment is deployed, we will identify, alongside your selected option, an additional sandbox and repeat the process.i.e. Always a sandbox & production pair where possible. Where there is no sandbox, we will migrate the production tenant as part of this second stage.
• If a customer has additional sandboxes, we will then proceed to migrate them.
• It is expected that there may be some development, and/or data migrations required on the customer side in order to start utilising the new capability. If any of our customers declare non-readiness by the dates supplied by Mambu, we will delay the migration for your tenant/s.

There is no anticipated downtime during the migration process, and in most cases it will take hours rather than days to complete. Please see the additional Mambu API v2 documentation that describes the new API endpoints as well as this User Guide. Should you have any questions about any aspect of the change, please don’t hesitate to contact your Mambu Customer Success Manager, who will work closely with you and us to help you understand everything to your satisfaction.

Please see an example timeline of the migration process including several steps for sandbox and production environments illustrated below:

An example timeline for the migration process:

February 2024 - May 2024: Customer carries out any necessary development
May 28th: First Sandbox Migration Commences
May 29th: First Sandbox Migration Completes / new Endpoints enabled
May 30th - June 12th: Customer UAT
June 14th: Production tenant Migration Commences
June 17th: Production Migration Completes / new Endpoints enabled
June 18th: Additional Sandbox/s Migration Commences
June 19th: Additional Sandbox/s Migration Completes / new Endpoints enabled
June 20th - June 21st: Testing on additional sandboxes (at customer discretion)

If you encounter any issues, you can reach out to your Customer Success Manager or to support@mambu.com with your questions for additional information or guidance.