Last updated 2026-06-02

Payment Reversal

Overview

This enhancement extends the existing reversal logic for accounting events and entries to now allow reversal even when settlements are present. It introduces a structured and consistent mechanism to create a reversed version of any accounting event, including complex linked entries.

Key Components

1. ReverseInitiatorEvent

This is the primary driver for initiating reversals. It constructs a new reversed event based on the original one.

  • Inputs: Original accounting event + associated entries
  • Outputs: Reversed version of the same type of event (e.g., reversing a PaymentEvent creates another PaymentEvent with opposite entry directions)

2. ReverseData

Encapsulates the original event and its entries. It is used by ReverseInitiatorEvent to generate a reversed event.

3. ReverseAccountingEvent

Acts as a wrapper for the actual reversed event, allowing the framework to distinguish between original and reversed operations. The end result is an event of the same type as the original, but with opposite semantics.

Entry Direction Reversal Logic

When reversing entries:

  • CREDIT becomes DEBIT
  • DEBIT becomes CREDIT

This ensures the financial effects of the original entries are fully nullified.

Settlement Reversal

If original entries contain settlements, the reversal process follows a two-step approach:

Step 1: Reverse Existing Settlements

  • For each settlement (e.g., between TENANT_PAYMENT_RECEIVED and CALL_FOR_RENT):
    • A new settlement is added in the opposite direction
    • This detaches the original entries

Step 2: Settle Original with Reversed Entries

  • Create a new settlement between each original entry and its reversed counterpart
  • This sets the openAmount of the original entry to zero

Relationships Between Events

Both the original and reversed events will have a relatedEvents field populated with mutual references. This helps in:

  • Tracing reversals
  • Visualizing event lineage

Reversing Payments

Reversing a Payment involves:

  1. Reversing the associated PaymentEvent using the logic above
  2. Creating a new Payment entity with:
    • origin = REVERSED
    • A relatedPayments field linking the original and reversed payments

Example: Payment Reversal Flow

  1. User triggers reversal of a payment
  2. PaymentEvent is reversed via ReverseInitiatorEvent
  3. Reversed PaymentEvent is created with inverted entry directions
  4. Settlements are reversed then re-linked with new reversed entries
  5. A new Payment with origin = REVERSED is created
  6. Mutual references are added via relatedPayments