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 redesigned interest rate management for savings products in 2023. This page addresses the redesign 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 the interest rate change history for each account.

interestAvailabilityKey: The unique identifier for each interest availability record.

type: In the 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 un-arranged 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 the EOD process), although the change is reflected in the 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 sequentially, and the processing status can be tracked when needed. For an example of this, see Make Bulk Deposits.

Live migration: This is an in-house solution that Mambu uses when we need an update on the data structure in order to accommodate a new implementation. This solution does not require any downtime and can be repeated if it fails for any reason. Live migration also guarantees data integrity.

What functional changes have been made?

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

• POST /deposits/{depositAccountId}:changeInterestRate
• POST /depositproducts/{depositProductId}:batchUpdate
• Interest rate changes for all existing accounts, on the Edit Product page of the Mambu UI.

This will take effect for the duration of the migration. Mambu will be providing backwards compatibility on the existing functionalities for a period of time, starting from Q3 2024. With the release and/or enabling of backwards compatibility, all endpoints and UI functions mentioned above will be available again after the migration is completed. However there are a few key points for users to be aware of when using the old interest rate change functions:

• POST /deposits/{depositAccountId}:changeInterestRate, POST /depositproducts/{depositProductId}:batchUpdate , and product propagation via the Mambu UI will start creating an interest availability record as well as an interest rate change transaction on the account, if used after the live migration.
• We strictly advise against using the old endpoints and product propagation in conjunction with the new interest availability endpoints. This is because of the risk of data loss, data discrepancy, and incorrect interest accruals.
• Product propagation - either done via the batchUpdate endpoint or from the Mambu UI for all existing and new accounts - will trigger a recalculation of the interest accrual from the last interest payment date for all accounts under that product to maintain the full backwards compatibility in the old interest rate management functionality.

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 the account id, start date, interest type and interest rate in the payload. Only the regular interest will be recognised, which should be specified as “type”: INTEREST in the request.

Rules and validations

• 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 and APPROVED states, the interest availability will become effective upon account activation.
• For accounts in a DORMANT state, the interest availability will become effective when the account becomes ACTIVE again. Once the account returns into an ACTIVE state, interest will be accrued and applied if the interest application date is involved, with the interest availability that was effective for the dormancy period.
• For accounts in a LOCKED state, the interest availability will become effective when the account is unlocked, and the account will be appraised to the point of the 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 two interest rate source options:
    • fixed: the interest rate can be changed as expected.
    • indexed: the Spread Default value can be changed. Spread Min and Spread Max values will adhere to the product configuration. The Index Source can be managed at the Admin level.
  • For TIERED BY BALANCE, the interest rate can be changed as expected.
  • For TIERED BY BANDS, the interest rate can be changed as expected.
  • For TIERED BY PERIOD, the start date can only be the current date. This interest rate term does not allow back- or future-dating the interest availability.
• Negative rates will be only allowed if the product configuration allows negative interest.

Use cases

Use case 1

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

Example account setup:

Assuming that this account has only one interest availability record:

If there is an interest rate change activity via POST /deposits/{depositAccountId}/interest-availabilities on 15/01/2024 with the following request body:

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

When this request is successfully processed, 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 a rate of 2.89%. This will be immediately reflected in the account.

Example: 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.

This example uses the same account setup from the previous case:

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

If there is an interest rate change activity via POST /deposits/{depositAccountId}/interest-availabilities on 16/01/2024 with the following request body:

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

When this request is successfully processed, 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).

Example: 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 will be recognised by the account appraisal process at EOD.

This example uses the same account as the previous use cases:

For this account there are now 3 interest availability records:

If there is an interest rate change activity via POST /deposits/{depositAccountId}/interest-availabilities on 19/01/2024 with the following request body:

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

When this request is successfully processed, 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).

Example: Interest Accrual calculation with an 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 allows users to make corrections or changes on an existing interest availability.

Rules and validations

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

Use case

This example uses the same account as the prior use cases:

Updating the IA xxx2:

In case of an interest rate change activity via PUT /deposits/{depositAccountId}/interest-availabilities/{interestAvailabilityKey} on 20/01/2024 with the following request body:

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

When this request is successfully processed, 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 immediately reflected in the account.

Example 1: 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)]

Example 2: Interest accrual calculation with an 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

Permissions required: VIEW_SAVINGS_ACCOUNT_DETAILS

Get interest availability for an account

Endpoint: GET /deposits/{depositAccountId}/interest-availabilities

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

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

• 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

• Permissions required: MAKE_BULK_CHANGE_INTEREST_AVAILABILITY
• This endpoint concludes two input parameters under the accountFilter wrapper as:
  • productId orencodedKey` of the product
  • Ids or the encodedKeys of the accounts.
• Product Id and Ids cannot be used in 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.
• To use Ids, at least one account Id must be provided.
• The startDate supplied should not be more than 31 days in the past. For future dates there is no limitation.
• When using Ids, the maximum number of account Ids that can be provided is 100,000 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}.
• Pagination

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:

The full response will only be available when the process reaches an ERROR or COMPLETE stage.

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 two different ways:

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

Mambu will:

1. Retrieve all accounts that are linked to the product Id or Ids provided in the request.
2. Post the new interest availability record to each one of those accounts.
3. Create an interest rate change transaction for every account retrieved.
4. 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?

Mambu will execute a live migration based on the process described below:

1. We will be migrating sandbox tenants within a regular release version, in Q3 2024.
2. Once the migration of a tenant has completed, the new IA endpoints will be exposed automatically.
3. During this migration you will not be able to use:
   1. The change interest rate API (fixed term interest only).
   2. The product propagation of any interest rate functionality - executed either through the UI or APIs.
4. After the completion of the migration, Mambu will be providing backward compatibility options for the existing interest rate change methods, from Q3 2024 for a definite period. Please see What changes from the existing functionality for details.
5. Production tenants will be migrated upon request.

There is no anticipated downtime during the migration process and endpoint enablement steps.

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.

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.