Common Processing Rules

Canopy allows for a wide range of customizations to support your lending product's needs, and we are constantly evolving to meet the unique requests of our users. While you consider how to model your product and workflows on Canopy, please be aware of the following common processing features.


Payment Pouring#

When a customer makes a repayment against their loan, Canopy applies that repayment to outstanding line item debts in a specific order known as payment pouring. Canopy's payment pouring process will first apply repayments to outstanding fees, then interest, then principal. Within each category (fee, interest, principal), older records will be repaid before newer records: the first fee entered for a customer will be repaid before the most recent fee.


Interest Accrual#

The interest calculation for accounts occurs at the end of each account's billing cycle as defined by the cycle_interval for the product associated with the account. The interest rate calculation for accounts is calculated via the following formula:

Interest calculation

Principal is the remaining principal in the account at the time of interest calculation.

Rate is the annual interest rate for your product.

Cycles is the number of billing periods in a year. This is derived from the product's cycle_interval. For example, a cycle_interval of 1 month would break out to 12 cycles per year.

See our article on product configuration for additional settings for customizing your product's interest calculation logic.

Canopy allows for retroactive events to factor into remaining principal in order to calculate interest. For example, if an account's billing cycle ends at the end of September and triggered an interest calculation, then a purchase can be entered retroactively after the interest calculation has been performed that will affect the balance used in end of month interest calculations based on purchase's effective_at date.

POST /line_items/payments: submit a retroactive payment event on 10/2/21 for 9/29/2021
{
"line_item_id": 345,
"effective_at": "2021-09-29T00:0:00+00:00",
...
}
GET line_items: retrieve line_item details
{
"line_item_id": 345,
"effective_at": "2021-09-29T00:0:00+00:00",
"created_at": "2021-10-02T00:0:00+00:00",
...
}

The payment's effective_date indicates when the payment was made by the customer, and Canopy will also save a created_at date to flag when this payment record was applied to the customer's account, and update the end of month interest according to this retroactive payment. See more about transactions here.

When performing this interest calculation, the resulting interest is rounded down to the nearest cent.


Identifying Resources on Canopy#

We are committed to keeping integration as simple as possible. When interfacing with Canopy's API's, you can pass your own system's identifiers to identify the same resource in Canopy.

For example, if you have a a customer record in your system:

idfirst_namelast_name
154JohnDoe

Then this customer be sent and retrieved with your id from the Canopy system of record:

POST /customers: create a new customer record
{
"customer_id": 154,
"name_first":"John",
"name_last": "Doe",
...
}
POST /accounts: assign this new customer to an account
{
"assign_customers": [
{
"customer_id": 154,
...
}
]
}

This pattern can be used for accounts, line_items, products, and more. Please see our API documentation for a full list of entities that can be created and synchronized with your system.