Learn Center has been sunset. Visit our new Docs site at: docs.canopyservicing.com
logo

Retroactive Event Processing

A subset of events that occur in Canopy are Retroactive.
📘
Retroactive Events: Changes to the present state of an account whose net result represents what would have happened if the history of events for the account were different. For example, a Payment Reversal is a retroactive event. It modifies the principal, interest, deferred interest, and fee balances of an account to represent the account state for if the payment had never occurred. ** Importantly, Retroactive Events do not modify the historical events on the account. They introduce new, current point in time offsets that create a comparable net effect.
Let’s look at the following two-column history of hypothetical events
Real World Activity
  • Account Creation
  • Charge ($50)
  • Charge ($50)
  • Payment ($50)
  • Interest ($5)
_______________
Net Principal: $50
Net Interest: $5
Net Fees: $0
Activity if the payment never occurred
  • Account Creation
  • Charge ($50)
  • Charge ($50)
  • Payment ($50)
  • Interest ($10)
  • Fee ($20)
_______________
Net Principal: $100 (+$50)
Net Interest: $10 (+$5)
Net Fees: $20 (+$20)
Notice that, in this example of a payment reversal, when we reverse the payment, the net effect is that: principal balance increases by $50, interest balance increases by $5, and fee balance increases by $50.
Accordingly, when the Payment Reversal occurs, it creates three offsets. The net effect is:
Payment Reversal [RETRO_VALID]: $75
  • PAYMENT_REVERSAL_PRINCIPAL: $50
  • PAYMENT_REVERSAL_INTEREST: $5
  • PAYMENT_REVERSAL_FEE: $20
The create a payment reversal API handles the reversal of the payment, as well as all of its downstream effects.

Best Practices for Reporting and Downstream Consumption

  • When Retroactive events such as payment reversals occur in our system, their output follows a parent-child relationship for intuitive consumption.
  • Downstream services consuming Canopy’s state need to be conscious of the structure in which retroactive events exist in our system, both when consumed through the API, and when consumed through our analytical interfaces or reporting exports. They appear as follows:
In our example:
Parent: Payment Reversal [RETRO_VALID]: $75
  • Child[VALID]: PAYMENT_REVERSAL_PRINCIPAL: $50
  • Child[VALID]: PAYMENT_REVERSAL_INTEREST: $5
  • Child[VALID]: PAYMENT_REVERSAL_FEE: $20
📘
Note: The RETRO_VALID parent line item does not impact balances; it is purely optical to house the child line item instead, each of the child line items drive the account balance calculations.
For top-level granularity, you may simply capture the total amount. In the API, this comes from the GET Line Items call, and is also visible in CanopyOS. Reporting queries should look for the parent line item.
For more detailed granularity, the top-level line item should be ignored, and instead, the children offsets should be observed. These speak to how the retroactive event affected each balance bucket. In CanopyOS, these are visible by clicking into the “Transaction Details” for any Retroactive Line Item. In the API, these are accessible via the GET /line_items/<line_item_type>/{line_item_id} endpiont. Reporting queries through DataDirect, or custom reporting structures also have access to the child line items.

Non-Retroactive Account Changes

  • Under certain operational conditions, you may not want to trigger retroactive event processing when modifying an account. This can be accomplished by direct changes to the account.
    • For example — if an account made a $50 payment, and you want to cancel out that payment without accounting for all of its downstream effects, you may simply choose to issue a Credit Offset of $50.

Powered by Notaku