This page contains a high-level description of the personal loan functionality. The details are available on the following pages:
Source of truth
The single source of truth for the system is Thought Machine and the loan account powered by the loan smart contract. The loan-manager is used for doing the calculations exactly the same way as the TM to provide the loan installment plan before opening a loan account and to provide the caching for the loans already opened.
The loan-manager listens to the events sent by the TM and reconstructs the installment plan with payments using them.
Kafka events
When the loan-manager sends the Kafka messages, it uses Avro encoding. The channels and schemas are described in GitHub repository.
https://github.com/SafiBank/SaFiMono/blob/main/common/schema/topicSchemasDefinitions.json
https://github.com/SafiBank/SaFiMono/tree/main/common/schema/schemas/loans
Showing preapproved limit
The preapproved limit shown on the dashboard is cached and it is refreshed by the following events:
The user opens an app (R + PT).
The user opens an open loan screen (R + PT).
The user tries to open a loan with particular parameters (OSP + R + PT).
OSP - Triggerring OneStop Platform workflow for risk recalculation.
R - Getting new score from risk microservice.
PT - Getting the products from the product recommendation tool using the risk score.
Listing of products
The product list provided to the customer is always based on the current version of the recommendation table using the current score provided by the risk microservice.
The OneStop Platform workflow is not triggered.
Opening a new loan
The opening of a new loan is controlled by the workflow to ensure all the parts are properly done. After receiving the request from the customer, the following steps are done:
The OSP workflow is triggered to update the risk score.
The current risk score is get from the risk microservice.
The matching products for the risk score are retrieved from the product recommendation table.
If the requested product does not match the available one, the loan opening is rejected.
A new loan account is opened in the Thought Machine.
The installment plan is generated and stored in the database.
The loan-manager waits for account creation and for the loan imbursement and initial fee payment.
The customer is notified the new loan was created.
Only one personal loan can be created at one time for the particular customer. The current limitation is at the debt manager and the frontend application. The rest of the system allows multiple loans per customer.
Auto deduction
On the due date at 0:01:00 local Philippines time time the current loan installment is made due by the loan smart contract. The loan-manager is informed about the amount of money that has to be paid and it issues the particular payment - it sends the posting to the TM.
If the customer has enough money on the main account, the installment is repaid. If not, the payment is rejected and it will be handled later by the overdue repayment logic.
Interest accrual
The interest accrual is done every day at 0:00:01 local Philippines time. It is handled completely by the loan smart contract as described in https://safibank.atlassian.net/wiki/spaces/ITArch/pages/150045119/Loan+installment+plan+calculation#Daily-accrual.
Overdue loan handling
If the current installment is not paid on the due date at 23:59:00 local Philippines time, it is made overdue by the smart contract. That means the due amount is zeroed out and the overdue amount is increased accordingly. The required amount is sent to the debt manager, that will auto deduct it from the main account or pocket whenever the customer has any incoming money.
For more information about debt manager see Debt Manager Documentation.
The loan installments principals and interests are handled using one debt manager bucket. That means that from the system perspective the whole loan has the one priority for repayments. The priority is described at https://safibank.atlassian.net/wiki/spaces/ITArch/pages/114819318/Debt+Manager+Documentation#%5BhardBreak%5DDebt-accounts-and-addresses.
When there is incoming money on the account, the debt is paid by the date of overdue installments, repaying the interest first, followed by the principal.
Early repayment
The early repayment can be performed on the loan where are no outstanding payments only.
User can perform the partial or fully early repayment. From the system perspective, there is no difference between them. The account is always closed as soon as the total outstanding debt is repaid.
The customers can choose if they want to recalculate the EMI after early repayment or not. If the EMI is recalculated the monthly installment amount is decreased. In the other case, the last repayment is lowered or the number of installment is decreased.
The customers enters the early repayment amount they want to pay and the system calculates the resulting change of the installment plan. If the customers agree and they have enough money on the account, the early repayment is done. In other case, the customers are informed about unsuccessful repayment.
Prepayment
The prepayment can be performed on the loan where are no outstanding payments only.
The prepayment allows customer to pay the future installments. The installment plan itself is not changed.
The prepaid amount is stored on the separate address of the loan account and it is maintained on the loan level. The individual installments are marked by the prepaid amount too, but this amount can be recalculated on the installment plan change (e.g. after early repayment).
Closing a loan
The loan is closed automatically when it is fully repaid. This can happen after following events:
The loan was fully early repaid or prepaid.
The auto deduction of the last installment was successfully done.
The overdue loan with no future installment was repaid.
The workflows is following:
The smart contract determines the total outstanding debt is zero.
The smart contract sends the loan-manager event to inform the account is supposed to be closed.
The loan-manager triggers TM to close the account.
The smart contract account closure logic is called.
The loan-manager waits until the loan is properly closed.