Additional comments on financial items & financial_entity_trxn records

docs/financial/financialentities.md

@@ -73,8 +73,10 @@ On creation of the order there will be a financial item for each line item and a
     For historical reasons this may not always be true but [it's the goal](https://github.com/civicrm/civicrm-dev-docs/issues/712). Financial items
     may not always be present in practice for pending contributions.
 
+**Financial items changes due to payments**
+
 When a payment is made it might either pay off all the line items, some of each of the line items, specific line items, in part or in full.
-Where a line item is now fully paid the status of the related financial item is updated o Paid. An `EntityFinancialTrxn` record is created
+Where a line item is now fully paid the status of the related financial item is updated to Paid. An `EntityFinancialTrxn` record is created
 in the `civicrm_entity_financial_trxn` table linking the payment to any line items it pays towards, specifying the amount paid on that payment.
 
 If the line item is paid in part then the financial item status should be 'Partly Paid' and the `EntityFinancialTrxn` record specifies the portion
@@ -83,14 +85,25 @@ of the line item that has been paid by that payment.
 For example if we have the scenario that an Order (Contribution) with 2 line items (values $100 & $200) is created then we will get
 
 * the order
-* 1 financial trxn record transferring the cost to accounts payable
-* 2 financial items (one for each line item for the full amount)
-* 2 financial entity transaction records linking the financial items to the accounts receivable transaction
+* 1 financial trxn record transferring the cost ($300) to accounts payable
+* 2 financial items (one for each line item for the full amount - ie amounts of $100 & $200)
+* 2 financial entity transaction records linking the financial items to the accounts receivable transaction - the amounts will be $100 & $200
 
 If we later get a payment for $100 we will see the following changes
 
-* 1 financial trxn record with is_payment. From account is accounts receivable, to account is the payment asset account (e.g Bank account)
-* 2 financial entity transaction records linking the financial items payment to the payment transaction.
+* 1 financial trxn record with is_payment and amount of $100. From account is accounts receivable, to account is the payment asset account (e.g Bank account)
+* 2 financial entity transaction records linking the financial items payment to the payment transaction (the payment is allocated proportionally
+so the amounts are $33.33 and $66.67).
+
+If that payment were to be cancelled (using the Payment.cancel api) we would see the following
+
+* 1 financial trxn record with is_payment = 1 and a negative amount equal to the original payment ($100 in this example). From account is the payment asset account, to account is accounts receivable.
+* 2 financial entity transaction records linking the financial items back to the payment reversal transaction. These are effectively reversing
+the financial entity transaction records linked to the original payment and the amounts are negative - ie -$33.33 and -$66.67)
+
+!! this same *should* happen for a negative payment although the allocation may be different. There may be a current bug here.
+
+**Financial items changes due to line item changes**
 
 If the line items change then the items financial items have to be updated. Generally the rule is to alter the zero out the
 old line item, reverse the financial items and then create a new line item with new financial items. However, this is not