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 a payment or payment_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

Related Articles

• Line Item Types
• Webhooks
• API: Reverse a payment for an account
• API: Reverse a charge for an account