This is an automated email from the ASF dual-hosted git repository.
arnold pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/develop by this push:
new 2f4705952 FINERACT-1968: Advance payment allocation - ASCII doc
2f4705952 is described below
commit 2f4705952b8dec7b75c9253ad83195bea366ba58
Author: Adam Saghy <[email protected]>
AuthorDate: Wed Aug 23 11:39:19 2023 +0200
FINERACT-1968: Advance payment allocation - ASCII doc
---
.../architecture/advanced-payment-allocation.adoc | 144 +++++++++++++++++++++
.../src/docs/en/chapters/architecture/index.adoc | 2 +
.../src/docs/en/images/payment_allocation_flow.png | Bin 0 -> 209511 bytes
3 files changed, 146 insertions(+)
diff --git
a/fineract-doc/src/docs/en/chapters/architecture/advanced-payment-allocation.adoc
b/fineract-doc/src/docs/en/chapters/architecture/advanced-payment-allocation.adoc
new file mode 100644
index 000000000..7b0bb98cb
--- /dev/null
+++
b/fineract-doc/src/docs/en/chapters/architecture/advanced-payment-allocation.adoc
@@ -0,0 +1,144 @@
+= Introducing Advanced payment allocation - WIP*
+
+Since the first repayment strategy got introduced, many followed, but there
was one thing common in them:
+
+* They were hard coding the allocation rules for each transaction type.
+
+By introducing the "Advanced payment allocation" the idea was to have a
repayment strategy which was:
+
+* supporting dynamic configuration of the allocation rules for transaction
types
+* supporting configuration of more fine-grained allocation rules for future
installments
+* supporting reprocessing of transactions and charges in chronological order
+
+== Glossary
+
+[cols="1,1"]
+|===
+
+|*WIP
+| Work in progress
+
+|*Advanced payment allocation
+| Ability to configure allocation rules dynamically for transactions
+
+|*Payment allocation
+|Rule that defines which outstanding balance to be paid of first on which
installment
+
+|*Re-amortization
+| Transaction amount to be divided into equal portions by the number of future
installments and those installments to be paid by these portions.
+|===
+
+== Capabilities
+
+* Payment allocation should be configurable for transactions:
+** Repayment
+** Goodwill credit
+** Payout refund
+** Merchant refund
+** Charge adjustments
+** Down payment (WIP)
+
+* Can be configured for Loan products
+** Payment allocation rule changes on the loan product will affect only the
newly created Loan accounts.
+
+* Chronological reprocess order
+** Transactions (including disbursements) and charges are (re)processed and
allocated in chronological order
+
+* Support re-amortization between future installments
+** Transaction amount to be divided into equal portions (based on the number
of future installments) and to repay each future installment by the calculated
portion.
+*** It's not hard coded, but usually the principal portion needs to be
allocated first, but if there are still unprocessed amounts, the rest of the
outstanding balances are to be allocated based on the rest of the rules
+
+* Main allocation rules (installment level)
+** Past Due Installment(s):
+*** Oldest first
+** Due Installment(s):
+*** Normal installment takes priority over Down-payment installment (if
applicable)
+** Future Installment(s):
+*** Available allocation orders:
+**** Next installment first
+**** Last installment first
+**** Re-amortization*
+* Secondary allocation rules
+** Penalty
+** Fee
+** Interest
+** Principal
+
+== Configuration
+
+Advanced repayment allocation rules can be configured for the Loan product if
"Advanced payment allocation" got selected as repayment strategy.
+
+There will be a (always required) “DEFAULT” transaction type configuration
which acts as fallback ruleset, if the there are no configured rules for a
specific transaction type.
+
+=== New repayment strategy
+* Name: Advanced payment allocation
+* Code: advanced-payment-allocation-strategy
+* Order: 8
+
+=== Allocation rules
+* Past due penalty
+* Past due fee
+* Past due principal
+* Past due interest
+* Due penalty
+* Due fee
+* Due principal
+* Due interest
+* In advance penalty
+* In advance fee
+* In advance principal
+* In advance interest
+
+==== Future installment allocation rules:
+* Next installment
+* Last installment
+* Re-amortization
+
+=== Example Request
+```
+{
+ ...
+ "paymentAllocation": [
+ {
+ "transactionType": "DEFAULT",
+ "paymentAllocationOrder": [
+ {
+ "paymentAllocationRule": "DUE_PAST_PENALTY",
+ "order": 1
+ },
+ {
+ "paymentAllocationRule": "DUE_PAST_FEE",
+ "order": 2
+ },
+ {
+ "paymentAllocationRule": "DUE_PAST_INTEREST",
+ "order": 3
+ },
+ ...
+ {
+ "paymentAllocationRule": "IN_ADVANCE_INTEREST",
+ "order": 14
+ }
+ ],
+ "futureInstallmentAllocationRule": "NEXT_INSTALLMENT"
+ }
+ ],
+ ...
+}
+```
+
+The above request configures the "DEFAULT" allocation rules:
+
+* First the already due penalties to be paid
+* Second the already due fees to be paid
+* Last the future interests to be paid
+
+Also for future installments set the allocation rules as
+
+* First future installment by due date to be paid first
+
+=== High level design
+
+Flow of advanced payment allocation processing
+
+image::{imagesdir}/payment_allocation_flow.png[]
diff --git a/fineract-doc/src/docs/en/chapters/architecture/index.adoc
b/fineract-doc/src/docs/en/chapters/architecture/index.adoc
index 7bb3c4b6f..01a635c6f 100644
--- a/fineract-doc/src/docs/en/chapters/architecture/index.adoc
+++ b/fineract-doc/src/docs/en/chapters/architecture/index.adoc
@@ -33,3 +33,5 @@ include::modules.adoc[leveloffset=+1]
include::business-date.adoc[leveloffset=+1]
include::reliable-event-framework.adoc[leveloffset=+1]
+
+include::advanced-payment-allocation.adoc[leveloffset=+1]
diff --git a/fineract-doc/src/docs/en/images/payment_allocation_flow.png
b/fineract-doc/src/docs/en/images/payment_allocation_flow.png
new file mode 100644
index 000000000..4b7be6fc3
Binary files /dev/null and
b/fineract-doc/src/docs/en/images/payment_allocation_flow.png differ
