Retroactive Event Processing
Our powerful capability allows you to modify different scenarios of events in your customer's accounts with our SOR System of Record, the core engine and database of Canopy that handles all calculations.
Overview
Retroactive events in Canopy enable the adjustment of an account's current state to reflect the ideal state of the account had certain historical events had been different while keeping the original historical events intact. This retroactivity is vital to the account state, as depending on the type of retroactive action being performed, the real world state of the account may require adjustments to outstanding principal, fees, interest, and/or account statuses. Note - retroactive events do not modify the actual history of an account; rather, they modify the current state of the account to reflect what a historical change in account activity would have produced.
Retroactive events can occur in our system in a few different ways
- A payment reversal or a charge reversal.
- Invalidating a pending payment.
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 to what they would be if the payment had never occurred.
Unsupported Retroactive Events
Currently, backdated charges and backdated payments are two event types that are not supported. If a backdated payment or charge is created, the account is not properly updated to reflect its new balance. That is, fees and interest are not re-calculated to give the account either a credit or debit offset. This needs to happen to keep our clients’ accounts accurate and compliant with what they expect to see in our system.
Endpoint Usage
Payment Reversals [and failed payments]
To initiate a payment reversal, the line_item_id of the payment line item must be provided to following the payment reversals endpoint:
POST /accounts/{account_id}/line_items/payment_reversals/{line_item_id}
The same retroactive process will also occur when a payment line_item in a pending status is marked to a failure state such as DECLINED via
PUT /accounts/{account_id}/line_items/{line_item_id}
This will initiate the retroactive process of reversing a payment. When viewed in CanopyOS, a new PAYMENT_REVERSAL line item will be added to the Transaction History of the account which will have an effective_at value of when the API call was made. While the retroactive engine is determining the corrective actions required to re-align the state of the account, this line item will be marked with a PROCESSING line item status. Upon completion, the line item will be updated with a RETRO_VALID status, marking the line item as completed and all retroactive impacts being patched onto the account.
Charge Reversals
To initiate a charge reversal, the line_item_id of the charge line item must be provided to following the charge reversals endpoint:
POST /accounts/{account_id}/line_items/charge_reversals/{line_item_id}
This will initiate the retroactive process of revering a payment. When viewed in CanopyOS, a new CHARGE_REVERSAL line item will be added to the Transaction History of the account which will have an effective_at value of when the API call was made. While the retroactive engine is determining the corrective actions required to re-align the state of the account, this line item will be marked with a PROCESSING line item status. Upon completion, the line item will be updated with a RETRO_VALID status, marking the line item as completed and all retroactive impacts being patched onto the account.
Frequently Asked Questions
How can I view the line item adjustments and offsets created from a retroactive action?
Once completed, the top level REVERSAL line item of the account may be queried through the Get Account Line Item endpoint. This will provide information on the top level REVERSAL line item, as well as any child line items produced as a result of the retroactivity.
Are there any webhooks re-sent as a result of retroactive processing?
The retroactive engine will analyze certain configurable webhooks to determine if the latest iterations of these webhooks should be scheduled for sending.
This includes the following webhooks:
minimum_payment_missedaccount_delinquency
In addition to scheduling the configurable webhooks, the line items generated as a result of the retroactive processing will experience the normal line item webhook behaviors. Consult Webhooks for more information.
How long does retroactive processing take?
On average, the retroactive processing of an account will take upwards of 2 minutes.
What is the difference between a refund/debit offset and a charge reversal?
A charge reversal is processed through the retroactive event processor, a refund on the other hand is not. The charge reversal will adjust the account to produce retroactively correct, interest, fees, and principal balances on the account.
For example - When reversing a $50 dollar charge, the final outputs of the reversal may exceed $50, as the original $50 charge may have incurred fees and interest. When issuing a $50 refund, the refund will be processed as is, and adjust the account balances for only the $50.
What is the difference between a refund and a payment reversal?
A payment reversal is processed through the retroactive event processor, a refund on the other hand is not. The payment reversal will adjust the account to produce retroactively correct, interest, fees, and principal balances on the account.
For example - When reversing a $50 dollar payment, the final outputs of the reversal may exceed $50, as the original $50 payment may have reduced fees and interest. When issuing a $50 refund, the refund will be processed as is, and adjust the account balances for only the $50.
Related Articles
Updated 7 months ago