Preview

Introduction

With Preview, you can gain valuable insights into the potential changes that would occur when creating a new loan, making a payment, initiating a payment reversal or restructuring one or multiple loans. By comparing the current state of an account with the hypothetical state after the desired action, Preview provides you with detailed differences in account details, line items, and the amortization schedule. This powerful feature allows you to visualize and evaluate the impact of various actions before committing to them, empowering you to make well-informed decisions for your lending operations.

Previewing actions before committing to them offers several advantages for your lending program. Here are a few scenarios where Preview can deliver value to your program:

Optimizing Loan Creation
By previewing different interest rates and loan cycles, you can assess the resulting differences in the amortization schedule, enabling you to choose the most suitable loan terms for your borrowers.

Transparent Payment Pouring
When making a payment, Preview allows you to see exactly how the payment will be poured among various line items. This visibility ensures accuracy and transparency in payment allocation.

Efficient Overpayments
Preview enables you to evaluate the impact of overpayments on the amortization schedule. By determining if a payment is sufficient to cover an entire future cycle, you can eliminate interest on the principal for that cycle, maximizing the benefit for your borrowers.

Confident Payment Reversals
When initiating a payment reversal, Preview helps you validate the account's status and identify any additional fees that may arise. This information minimizes any potential impact on the account's payment history.

Capabilities

Canopy’s Preview feature allows you to:

Preview the effects a supported action would have on an existing account, making no changes and having zero side-effects on the provided account
Provide all differences in the state of an account that would be caused by committing the previewed action
Provide borrowers the possibility of knowing exactly what would change on their account when making a payment or creating a new loan

Currently, Preview supports the following actions:

Creating a new loan
Making a payment
Reversing a payment
Restructuring one or multiple loans

Any configuration that can be specified when taking any of the above actions can be provided to Preview as well.

This includes:

The principal of the payment or the loan
Loan term, fee and interest policies in the case of a loan
The payment that will be reversed in the case of a payment reversal
The strategy to handle outstanding interest and fee balances on the original loan in the case of a loan restructuring

How to Use

Preview supports an effective_at parameter. This represents the effective at date and time for the action. In this case, the account’s time will be processed up to this date for the purpose of the current preview only.

In a scenario where the provided date is past additional due dates or statement cuts, they will be included in the differences returned.

Preview can be accessed through CanopyOS or using the following endpoint:

GET /accounts/{{account_id}}/preview/{{action}}?action_body={{url_encoded_body}}

The currently supported actions are:

CREATE_LOAN
CREATE_PAYMENT
REVERSE_PAYMENT
RESTRUCTURE_LOANS

Here are the steps you'll want to take when using the above API endpoint:

Make a POST request to a supported action endpoint (e.g., payment creation) -- be sure to include the preview header
The API will respond with a 303, and the Location header of the response is set to the preview endpoint
Make a GET request to the endpoint received in the previous response's Location header (the preview endpoint, including the url-encoded body of the POST request)
The API will respond with the diffs generated by preview

Request Format

The request has no body. Instead, the body of the action being previewed is passed as a URL encoded string in the action_body query parameter. This is the same body one would normally use for a POST request to perform the action.

If an effective_at is provided, the action will be effective at the provided date, otherwise the current time will be used. For the context of the preview only, the account’s time will be rolled up to one minute past the provided effective_at. No side-effects are caused when previewing any action.

Response Format

Example body of a previewed payment

This is an example of making an exact payment on time for a loan

min pay is 647
principal is 500
interest is 147

{
    "diffs": {
        "details": {
            "min_pay_due_cents": {
                "min_pay_cents": 0
            },
            "additional_min_pay_details": {
                "current_min_pay_cents": 0
            },
            "summary": {
                "total_balance_cents": 5500,
                "principal_cents": 5500,
                "interest_balance_cents": 0,
                "am_interest_balance_cents": 0,
                "total_paid_to_date_cents": -647,
                "total_interest_paid_to_date_cents": 147,
                "available_credit_cents": 1994500,
                "total_payoff_cents": 5500
            }
        },
        "line_items": {
            "test-novo-719": {
                "principal_cents": 5500
            },
            "can_337": {
                "principal_cents": 0
            },
            "new": {
                "0x1234k6mj2z": {
                    "account_id": "can_2",
                    "line_item_id": "0x1234k6mj2z",
                    "line_item_type": "PAYMENT",
                    "line_item_status": "VALID",
                    "effective_at": "2022-09-16T09:11:28+00:00",
                    "original_amount_cents": -647,
                    "external_id": null,
                    "allocation": null,
                    "fee_policies": null,
                    "interest_policies": null,
                    "am_len": null,
                    "merchant_data": null,
                    "external_fields": null,
                    "description": "upd payment principal_cents: -647 + 647",
                    "product_id": "can_1",
                    "json_col": null,
                    "principal_cents": 0,
                    "parent_id": null
                },
                "can_339": {
                    "account_id": "can_2",
                    "line_item_id": "can_339",
                    "line_item_type": "PAYMENT_SPLIT",
                    "line_item_status": "SPLIT_VALID",
                    "effective_at": "2022-09-16T09:11:28+00:00",
                    "original_amount_cents": -147,
                    "external_id": null,
                    "allocation": null,
                    "fee_policies": null,
                    "interest_policies": null,
                    "am_len": null,
                    "merchant_data": null,
                    "external_fields": null,
                    "description": "charge payment child",
                    "product_id": "can_1",
                    "json_col": null,
                    "principal_cents": 0,
                    "parent_id": 352
                },
                "can_340": {
                    "account_id": "can_2",
                    "line_item_id": "can_340",
                    "line_item_type": "PAYMENT_SPLIT",
                    "line_item_status": "SPLIT_VALID",
                    "effective_at": "2022-09-16T09:11:28+00:00",
                    "original_amount_cents": -500,
                    "external_id": null,
                    "allocation": null,
                    "fee_policies": null,
                    "interest_policies": null,
                    "am_len": null,
                    "merchant_data": null,
                    "external_fields": null,
                    "description": "loan payment child",
                    "product_id": "can_1",
                    "json_col": null,
                    "principal_cents": 0,
                    "parent_id": 351
                }
            }
        },
        "am_forecast": {
            "0": {
                "am_cycle_payment_cents": -647,
                "paid_on_time": true
            }
        }
    },
    "complete_am_forecast": [
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2022-08-23T00:00:00-04:00",
            "min_pay_due_at": "2022-09-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": -647,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 6147,
            "am_end_total_balance_cents": 5500,
            "am_start_principal_balance_cents": 6000,
            "am_end_principal_balance_cents": 5500,
            "paid_on_time": true,
            "created_at": "2023-07-26T14:32:47.797326-04:00",
            "updated_at": "2023-07-26T14:32:47.797326-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2022-09-23T00:00:00-04:00",
            "min_pay_due_at": "2022-10-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 5647,
            "am_end_total_balance_cents": 5000,
            "am_start_principal_balance_cents": 5500,
            "am_end_principal_balance_cents": 5000,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.80078-04:00",
            "updated_at": "2023-07-26T14:32:47.80078-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2022-10-23T00:00:00-04:00",
            "min_pay_due_at": "2022-11-18T00:00:00-05:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 5147,
            "am_end_total_balance_cents": 4500,
            "am_start_principal_balance_cents": 5000,
            "am_end_principal_balance_cents": 4500,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.8008-04:00",
            "updated_at": "2023-07-26T14:32:47.8008-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2022-11-23T00:00:00-05:00",
            "min_pay_due_at": "2022-12-18T00:00:00-05:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 4647,
            "am_end_total_balance_cents": 4000,
            "am_start_principal_balance_cents": 4500,
            "am_end_principal_balance_cents": 4000,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800804-04:00",
            "updated_at": "2023-07-26T14:32:47.800804-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2022-12-23T00:00:00-05:00",
            "min_pay_due_at": "2023-01-18T00:00:00-05:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 4147,
            "am_end_total_balance_cents": 3500,
            "am_start_principal_balance_cents": 4000,
            "am_end_principal_balance_cents": 3500,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800808-04:00",
            "updated_at": "2023-07-26T14:32:47.800808-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-01-23T00:00:00-05:00",
            "min_pay_due_at": "2023-02-18T00:00:00-05:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 3647,
            "am_end_total_balance_cents": 3000,
            "am_start_principal_balance_cents": 3500,
            "am_end_principal_balance_cents": 3000,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800811-04:00",
            "updated_at": "2023-07-26T14:32:47.800811-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-02-23T00:00:00-05:00",
            "min_pay_due_at": "2023-03-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 3147,
            "am_end_total_balance_cents": 2500,
            "am_start_principal_balance_cents": 3000,
            "am_end_principal_balance_cents": 2500,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800815-04:00",
            "updated_at": "2023-07-26T14:32:47.800815-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-03-23T00:00:00-04:00",
            "min_pay_due_at": "2023-04-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 2647,
            "am_end_total_balance_cents": 2000,
            "am_start_principal_balance_cents": 2500,
            "am_end_principal_balance_cents": 2000,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800819-04:00",
            "updated_at": "2023-07-26T14:32:47.800819-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-04-23T00:00:00-04:00",
            "min_pay_due_at": "2023-05-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 2147,
            "am_end_total_balance_cents": 1500,
            "am_start_principal_balance_cents": 2000,
            "am_end_principal_balance_cents": 1500,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800823-04:00",
            "updated_at": "2023-07-26T14:32:47.800823-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-05-23T00:00:00-04:00",
            "min_pay_due_at": "2023-06-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 1647,
            "am_end_total_balance_cents": 1000,
            "am_start_principal_balance_cents": 1500,
            "am_end_principal_balance_cents": 1000,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800826-04:00",
            "updated_at": "2023-07-26T14:32:47.800826-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-06-23T00:00:00-04:00",
            "min_pay_due_at": "2023-07-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 1147,
            "am_end_total_balance_cents": 500,
            "am_start_principal_balance_cents": 1000,
            "am_end_principal_balance_cents": 500,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800829-04:00",
            "updated_at": "2023-07-26T14:32:47.800829-04:00"
        },
        {
            "line_item_id": "test-novo-719",
            "line_item_description": null,
            "cycle_exclusive_end": "2023-07-23T00:00:00-04:00",
            "min_pay_due_at": "2023-08-18T00:00:00-04:00",
            "am_min_pay_cents": 647,
            "am_cycle_payment_cents": 0,
            "am_interest_cents": 147,
            "am_deferred_cents": 0,
            "am_fees_cents": 0,
            "am_principal_cents": 500,
            "am_start_total_balance_cents": 647,
            "am_end_total_balance_cents": 0,
            "am_start_principal_balance_cents": 500,
            "am_end_principal_balance_cents": 0,
            "paid_on_time": null,
            "created_at": "2023-07-26T14:32:47.800842-04:00",
            "updated_at": "2023-07-26T14:32:47.800842-04:00"
        }
    ]
}

The response will only return the differences between the account’s current state, and the state it would be in had the previewed action been properly committed. Additionally, if a future date is passed in the effective_at parameter, any events leading up to that date will also show up in the list of differences.

The body of the response is a JSON of the following structure:

{
	"diffs": {
		"details": {
		  // Same format as a GET on an account
		},
		"line_items": {
			// A list of line item changes
		},
		"am_forecast":{
			// A list of amortization schedule changes
		}
	},
	"complete_am_forecast": {
		// The entire amortization schedule as it would be if the previewed action had been performed
	}
}

Frequently Asked Questions

What is Preview?

Preview is a powerful tool that helps borrowers and lenders have a clear picture of how their loan decisions will impact their financial situation.
It allows customers to see the consequences of actions like taking a draw or making an overpayment before actually doing it.
So, instead of being unsure about the outcome, they can make informed choices and avoid any surprises.
This feature brings more transparency, confidence, and control to customers' borrowing experience.
With Preview, customers can confidently manage their loans, avoid unnecessary fees, and plan their finances more effectively.
It's all about empowering customers to make smarter decisions and have a better grasp of their financial future.

What actions can I preview?

Using the Canopy API, you can preview creating a new loan, making a manual payment, processing a payment reversal or restructuring one or multiple loans. Within CanopyOS, you can preview making a manual payment or processing a payment reversal.

How is Preview different from LoanLab?

Preview allows borrowers to preview the impact of potential changes to their accounts before making them, providing confidence in the expected outcomes. It focuses on real-time decision-making support for borrowers with actual production data.
Preview not only lives within CanopyOS workflows but also can be used as a tool within other lending program workflows. Customers can build their own solutions with Preview.
On the other hand, LoanLab is primarily used for experimenting in QA and UAT environments. It allows users to test different scenarios and configurations from scratch.