Guides

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.

Suggest Edits

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

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 the PAYMENT_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 an original_amount_cents of 5000 is effective for 2023-02-02
  • A PAYMENT transaction originally effective for 2023-02-01 is reversed on 2023-02-15 and as a result it determined that the AM_INTEREST should have had an original_amount_cents value of 12000, meaning there needs to be a 7000 adjustment to the interest balance of the account
  • An adjustment will be created, with a transaction type of AM_INTEREST, an original_amount_cents value of 7000, an effective_at value of 2023-02-02, an issued_at value of 2023-02-15, an adjustment_for_transaction_id referencing the transaction_id of the original AM_INTERESTeffective for 2023-02-02, and a adjustment_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:

🚧

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 6 months ago