Policy Configurations

A policy is defined as: any behavior from Canopy’s system that you would like to see enforced over a borrower’s lifecycle.

As a computation engine, Canopy strives to enforce all policies that you ask it to for all of your borrowers, which are necessary for running your lending program. In order to make sure that Canopy is behaving as expected, you will need to - “in code” communicate “plain-english” policies to the system.

A Few “Plain-english” Examples

Interest should accrue at the end of each cycle, following the average daily balance formula.

Late fees of $20 dollars should accrue every time the borrower misses a payment, with the first late fee automatically waived.

Statements should cut every 1 month, adjusting for the end-of-month.

🎯

The goal of this guide is to teach you how to ask (in code / by configuration) Canopy to enforce the policies you would like for it to enforce.

Types of Policies

At a high level, policies can be defined in Canopy in one of six places:

Configuration Layer Policies

Organization-level: These are enforced for all borrowers your team onboards, unless overridden at the product, account, or line-item level. Common examples include risk management or compliance rules unique to your domain. Generally, organization-level configs are very rare, and unique to enterprise contracts.

Product-level: These are enforced for all borrowers onboarded with a specific product_id, unless overridden at the account or line-item level. A common example is the cycle length of the borrower. These are configured in your create product payload. Those that are safe to edit can be edited with subsequent API calls.

Account-level: These are unique to each borrower onboarded with a specific product_id, unless overridden at the line item level. A common example is the borrower’s interest rate. These are configured in your create account payload. Those that are safe to edit can be edited with subsequent API calls.

Line-item-level: These are unique to each line item for a borrower. A common example is: two charges that have two different interest rates. These are configured in your create line item payloads.

System Enforced Policies

Event-driven: These policies are encoded to fire at the execution of an event. Their logic can live in one of two places:

Webhooks → The logic lives in your system and is enforced via call-and-response. For example; Canopy notifies you when the borrower has missed a payment. In response to the notification, you query the account’s state, determine whether you would like to create a fee / change the account status, and then issue API requests to the create fee and update account status API endpoints. In this pattern, Canopy does not enforce the logic of your policy, but does enforce its outcome. This pattern is very common to get complex and highly policies up and running, and gives your team complete control over how the policy gets enforced in Canopy’s system.
Internal Hooks → [Enterprise Only] The custom logic for the policy is encoded directly into Canopy. When the event fires, Canopy automatically enforces the custom logic based on your team’s business requirements, instead of having the logic live in your webhook handler.

Implicit

Unfortunately, some behavior in Canopy, as with any System of Record, is simply implicit. We do our best to document implicit behaviors rigorously, but their impact is unique to your workflow. To make sure your lending program is resilient to implicit policies, we recommend the following best practices:

Enterprise: Take time with our Technical Support team into your onboarding. Our team will work with yours to make sure that we write test cases that confirm that the system behaves as expected for you.
Enterprise: Any implicit policy in Canopy can be moved into either a Configuration Layer Policy or a System Enforced Policy. Work with our team to scope these into your SOWs.
General: The next tutorial will be about testing your core workflow — using this tutorial, you should be able to construct test cases that ensure that no Implicit Policies in Canopy are creating unexpected outcomes for test cases in your lending program.

👋

Enterprise contract? In large part, our enterprise contracts are scoped to include policies that we don’t support today. In order to scope these contracts, it’s helpful for you to get as close as you can to enforcing the policies you need to enforce, and then figuring out which policy, at which level, is needed to meet the specific needs of your lending program.

Quickstart Policy Configurations