Adam Saghy created FINERACT-2939:
------------------------------------
Summary: Down payment fee refund on Merchant issued refund and
Payout refund
Key: FINERACT-2939
URL: https://issues.apache.org/jira/browse/FINERACT-2939
Project: Apache Fineract
Issue Type: New Feature
Components: Charges
Affects Versions: 1.15.0
Reporter: Adam Saghy
Assignee: Adam Saghy
*Summary:* Calculate and create a "Fee refund" transaction for Down payment
fees when a Merchant issued refund or Payout refund is posted, pro-rated by the
refund-to-total-disbursed ratio
h4. Background
Fineract can already create an *Interest refund* transaction for Merchant
issued refund and Payout refund transactions, configured on the loan product
through supportedInterestRefundTypes. There is no equivalent for fees. The Down
payment fee from the previous story is currently never refunded when the
customer gets money back from the merchant.
h4. Goal
Allow the system to be configured to calculate and create a *Fee refund*
transaction, like Interest refund, when a Merchant issued refund or Payout
refund is posted.
h4. Acceptance criteria
# *Configuration*
* The loan product and loan get a new attribute (for example
supportedFeeRefundTypes) that lists which refund transaction types
(MERCHANT_ISSUED_REFUND, PAYOUT_REFUND) trigger a Fee refund. It mirrors
supportedInterestRefundTypes.
* The loan inherits the value from the product, and it can be overridden where
Interest refund allows it.
# *Eligible fees and calculation*
* *Eligible fees:* only *Down payment fee* charges are in scope. Other charge
types (Disbursement fee, specified due date fees, installment fees and so on)
are not refunded.
* *Ratio:* refund ratio = refund amount / *total disbursed amount* of the
loan, summed across all disbursements.
* *Multiple fees:* the same ratio applies to *every* Down payment fee on the
loan, including fees from different disbursements and down payment periods and
multiple fees on the same period.
* *Formula:* Fee refund amount = refund ratio × sum of all Down payment fee
amounts.
* *Waivers and adjustments:* the calculation uses the *original charged
amount* of each fee. Waivers and charge adjustments do not reduce the base.
* *Rounding* follows the loan currency and rounding settings.
* *Cap:* the cumulative Fee refund across multiple refunds never exceeds the
total Down payment fee amount.
*Example: single disbursement*
* Disbursement $1,000; down payment $250; Down payment fee $25
* Merchant issued refund of $500 → ratio 50% ($500 / $1,000)
* Fee refund = 50% × $25 = *$12.50*
*Example: multiple disbursements*
* Disbursement 1: $1,000 → down payment $250 → Down payment fee $25
* Disbursement 2: $500 → down payment $125 → Down payment fee $12.50
* Total disbursed $1,500; total Down payment fees $37.50
* Merchant issued refund of $750 → ratio 50% ($750 / $1,500)
* Fee refund = 50% × $37.50 = *$18.75* ($12.50 from fee 1 + $6.25 from fee 2)
# *Transaction handling*
* *New type:* a transaction type *"Fee refund"* is created automatically,
linked to the triggering refund transaction (like Interest refund).
* *Credit behaviour:* Fee refund is a *credit* transaction and is allocated
like any other credit or repayment-type transaction, following the configured
allocation rules. It is not tied to the Down payment fee it was calculated from:
** if the Down payment fee (or other balance) is still outstanding, the Fee
refund may reduce it, depending on the allocation rules,
** otherwise it goes to other outstanding balances, or to overpayment if
nothing is outstanding.
* *Reversal:* reversing or undoing the triggering refund also reverses the
linked Fee refund.
* *Recalculation:* backdated refunds, backdated disbursements and
reverse-replay recalculate the Fee refund correctly.
# *Accounting and events*
* Journal entries for Fee refund use the agreed GL mappings.
* Business events are raised for the new transaction type.
* The Fee refund appears in the transaction history and in loan summary
figures.
*Testing*
* Integration and E2E tests cover:
** Merchant issued refund and Payout refund (each enabled or disabled through
configuration)
** partial and full refunds
** multiple refunds, including the cap
** single and multiple disbursements with multiple Down payment fees
** multiple Down payment fees on the same down payment period
** Down payment fee paid vs. unpaid at refund time (credit allocation)
** waived or adjusted Down payment fees (refund calculated on the original
amount)
** reversal of the refund
** backdated refunds and reverse-replay
h4. Out of scope
* Refund of any fee other than Down payment fee.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
