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 reversing a charge. 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.
Understanding API output
Payment Reversals (or payment failure) in Canopy increase an account’s balance in two ways:
- Reintroduced balances: The payment being reversed paid down some portion of interest, fees, and principal balances. This balance needs to be reintroduced by the reversal.
- Retroactive balances: If the payment never occurred, overall interest and fees for the account may need to be higher. For example:
- If the balance should have been higher, the borrower may need to have accrued more daily interest than they actually did
- If the borrower’s payment helped them avoid a late fee, that payment’s failure means the late fee would have been assessed.
Our interface helps you reconcile and granularize a payment reversal, as well as understand how it breaks down to each of those categories:
- Both when observing a
statement
and when observing apayment
orpayment_reversal
line item.
Reminder:
Every time a payment gets processed in our ledger, it gets SPLIT to cover 3 types of balances (
PRINCIPAL
,INTEREST
,FEES
- depending on your product policy).
At a Transaction/Line_item level
For every transaction (line_item
) in our system, there is a field line_item_relationships
that describes its relation to other transactions in the system. E.g. a payment reversal would ALWAYS have a related payment.
E.g. for a payment with "line_item_id": "can_67890"
you can get:
"line_item_relationships": [
{
"type": "PAYMENT_REVERSAL",
"line_item_id": "can_12345"
}
]
Similarly, if you request information about the payment reversal ("line_item_id": "can_12345"
), you would find its relation to the payment in question.
GET …/line_items/can_12345
:
"line_item_relationships": [
{
"type": "PAYMENT",
"line_item_id": "can_67890"
}
]
However, it gets more granular in the "line_item_relationship_summary
". Looking at the body of the payment reversal response:
"line_item_relationship_summary": {
"payment_parent_id": "can_67890",
"original_payment_amount_cents": -3900,
"splits_fees_cents": 0,
"splits_interest_cents": 1000,
"splits_principal_cents": 2900,
"newly_introduced_fees_cents": 0,
"newly_introduced_interest_cents": 0,
"payment_credit_balance_cents": 0
}
With the example of the payment reversal, we can see another reference to the original -3900
¢ payment (can_67890
). Given the original payments SPLITS processed (fees, interest, principal) are reversed, you see positive balances for "splits_interest_cents": 1000
and "splits_principal_cents": 2900
.
If there was any net new fees/ interest introduced (e.g. there was a long time between payment and its reversal), they would go appear under "newly_introduced_fees_cents""newly_introduced_interest_cents"
.
In special cases, where the payment created a credit balance (a.k.a. negative balance), the reversal would surface credit balance reversed inside "payment_credit_balance_cents"
.
At a Cycle/Statement level
At the end of the billing cycle, all retroactive impacts made effective within the cycle will be summarized on the statement under the following categorical fields:
Interest
cycle_payment_reversal_interest_cents
cycle_payment_reversal_interest_split_cents
cycle_total_payment_reversal_interest_cents
Fees
cycle_payment_reversal_fees_cents
cycle_payment_reversal_fees_split_cents
cycle_total_payment_reversal_fees_cents
Principal
cycle_payment_reversal_principal_split_cents
All of the fields above follow a similar pattern:
cycle_payment_reversal_[balance]_cents
- refers to net new balance (interest/ fees) accrued within the cycle as a result of a reversal. This includes balances which should have accrued on the account in the previous billing cycles (as if the reversed transaction never happened).
Note:
There is no net new principal balance introduced by reversals.
cycle_payment_reversal_[balance]_split_cents
- re-introduced balances, which had already been accrued on the account, either prior to or within the cycle (before getting paid down by the payment reversed).
For example:
There used to be multiple LATE_FEE transactions on an account that got poured into by a subsequent payment (generating
splits_fees_cents
).That payment got reversed and those
LATE_FEE
transactions were re-introduced.
cycle_**total**_payment_reversal_[balance]_cents
- the total sum of (interest/fee) balance adjustments as a result of all reversal activity within the billing cycle.
This is essentially the sum of the two fields before it:
cycle_payment_reversal_[balance]_cents
+ cycle_payment_reversal_[balance]_split_cents
Total
- cycle_reversal_split_cents - this is just a sum of ALL reintroduced balances WITHOUT net new balances.
cycle_payment_reversal_interest_split_cents
+
cycle_payment_reversal_fees_split_cents
+
cycle_payment_reversal_principal_splits_cents
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_missed
account_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 11 months ago