Transaction Reversals
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
Reversal activity in Canopy enables the retroactive correction of account activity through adjustments of an account's current state to reflect the ideal state of the account had the historical activity been different. These adjustments maintain the original historical account state and are vital to the account state, as depending on the type of reversal action being performed, the state of the account may require changes to outstanding principal, fees, interest, account statuses, and/or amortization schedules.
The current list of transactions that support reversals are:
- A payment reversal
- A debit offset reversal
Transaction reversals are a retroactive event that require asynchronous processing. They adjust the principal, interest, deferred interest, and fee balances of existing transaction balances on the account, and issue net new adjustment transaction that are backdated to correct the account state to what it should be if the original transaction had never occurred.
To see a Step by Step walkthrough of a Payment Reversal click this link.
![Payment Reversal](https://files.readme.io/558361e-Payment_Reversal.png)
Endpoint Usage
Payment and Debit Offset Reversals
To initiate a reversal of either a PAYMENT
or DEBIT_OFFSET
, the transaction_id
of the transaction record must be provided to following the payment reversals endpoint:
POST /accounts/{account_id}/line_items/payment_reversals/{transaction_id}
This will initiate the retroactive process of reversing the transaction. When viewed in CanopyOS, a new PAYMENT_REVERSAL
transaction will be added to the Transaction History, 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 adjust the state of the account, the PAYMENT_REVERSAL
will be in a PROCESSING
status. Upon completion, the PAYMENT_REVERSAL
will be updated to a RETRO_VALID
status, marking the transaction reversal as completed and all retroactive adjustments being applied onto the account.
Once the reversal has completed processing, the original reversed transaction will be updated with:
reversed_by_transaction_id
- linking the reversed transaction to thePAYMENT_REVERSAL
reversed_at
- marking when the reversed transaction was reversed
Payment Reversal Webhook
Upon completion of the reversal processing, a payment_reversed
webhook detailing a summary of the reversal will be delivered to the client (if webhooks are configured).
Example Webhook Payload:
{
"account_id": "can_1234",
"payment_reversal_line_item_id": "can_5678",
"reversed_payment_line_item_id": "can_4532",
"effective_at": "2024-02-20T09:12:14+00:00",
"reversal_original_amount_cents": 5000,
"total_fee_adjustments_cents": 1000,
"total_interest_adjustments_cents": 432
}
Webhook Attribute Breakdown
account_id
- The id of the account on which the transaction reversal belongs to.payment_reversal_line_item_id
- The id of the transaction reversal activity.reversed_payment_line_item_id
- The id of the transaction which had been reversed.effective_at
- The effective datetime for when the transaction reversal occurred.reversal_original_amount_cents
- The amount of reversal transaction, in cents.total_fee_adjustments_cents
- The net sum of all new fee type adjustments applied on the account as a result of the reversal.total_interest_adjustments_cents
- The net sum of new interest type adjustments applied on the account as a result of the reversal.
Retroactive Interest and Fee Adjustments
A reversed transaction can lead to retroactive differences in interest and fee balances on the account's transaction history that need to be corrected. Once a reversal has completed its processing, these differences will surface on the account as net new transaction activity with backdated effective_at
values, which represents when the transaction should have historically taken effect. To ensure traceability of these changes, these new adjustment transactions will have an issued_at
value which matches the date and time of when the transaction reversal occurred.
Any adjustment transaction issued to correct an already existing interest or fee balance will reference that existing transaction record through the adjustment_for_transaction_id
, available on the endpoint GET Account Transactions. These adjustments will also reference the reversal transaction that caused their creation through adjustment_by_transaction_id
.
Example:
- There exists an
AM_INTEREST
transaction with anoriginal_amount_cents
of5000
is effective for2023-02-02
- A
PAYMENT
transaction originally effective for2023-02-01
is reversed on2023-02-15
and as a result it determined that theAM_INTEREST
should have had anoriginal_amount_cents
value of12000
, meaning there needs to be a7000
adjustment to the interest balance of the account - An adjustment will be created, with a transaction type of
AM_INTEREST
, anoriginal_amount_cents
value of7000
, an effective_at value of2023-02-02
, anissued_at
value of2023-02-15
, anadjustment_for_transaction_id
referencing the transaction_id of the originalAM_INTEREST
effective for2023-02-02
, and aadjustment_by_transaction_id
referencing the transaction id of the reversal activity that caused the issuance of the adjustment.
Payment Repouring
When reversing a transaction, any payment type activity which had applied to the account will have their balances re-poured on the account's transactions. This includes new adjustments issued through the reversal activity itself. All existing balance split activity tied to the re-poured activity will be updated to include a discarded_at
and discarded_by_transaction_id
to identify what reversal activity caused their discardment and when they were discarded. Note: Discarded balance splits no longer impact account balances and should only be utilized for reconciliation.
Frequently Asked Questions
How can I view the adjustments and balance corrections created from a reversal action?
The complete impact of a given reversal can be viewed in the transaction detail drawer for that reversal in CanopyOS. The "Transactions Impact" component displays the account activity from the payment to the reversal, highlighting interest and late fees added as a result of the reversal, as seen here:
![](https://files.readme.io/b758f52-Transactions_Impact.png)
Coming Soon
New APIs are currently under development to expose a convenient interface for these capabilities. We will make a release announcement once they are available.
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 transaction adjustments 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 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 3 months ago