Introduction

Payments are at the core of any lending program; as such, it’s important to understand how Payments work within the Canopy ledger. Payments are a special type of transaction in Canopy. This guide assumes that you are familiar with the Transactions guide.

Payments in the Canopy ledger are a class of line items. The simplest example within the class is the PAYMENT line item. This represents a payment made by the borrower to the lender. There are also several other non-PAYMENT line items which are considered payments in the context of the Canopy ledger.

Payments are any line items which start with a negative principal balance. The negative principal balance from payment line items will be used to offset positive principal from outstanding charges, loans, interest, fees, etc. on the account. These offsets will reduce the total outstanding balance on the account.

Key Features

Pouring

Payments, like all line items, have an effective_at attribute which signifies the date and time at which the payment should be considered to be in effect. Once this effective_at time has elapsed, the Canopy ledger will process the payment by “pouring” its negative principal balance into positive principal balances in other line items.

Note that payments which are created with a PENDING line item status will still be poured after their effective_at has elapsed. If the payment subsequently transitions to a DECLINED or INVALID line item status, Canopy will process a reversal (TODO: backlink to reversals docs) on the account to accurately account for the state of the account as if the payment was never attempted.

During this “pouring” process, Canopy sorts all the outstanding line items on the account in order of priority, paying down (generally, see caveats below) fees, then interest, then principal - oldest first to newest last.

📘

Caveat: Loans

Loans are poured into in a special way by the ledger. Each cycle, a portion of the total outstanding balance on the loan is due. Canopy will pay down the oldest due portions of the loan first, working towards the newest due portions of the loan. Once all due portions of the loan have been paid off, Canopy will pour the remainder of the payment towards the principal balance of the loan.

Payment Obligations

Payments made by borrowers are generally made to satisfy an obligation to pay the lender. These obligations come in the form of a statement issued to the borrower at the end of each cycle or an agreed upon repayment schedule. The Canopy ledger knows when the payment is due and how much the payment obligation is, and as such will react to the behavior of the borrower. This includes updating the current amount due as well as potentially issuing the borrower a late fee should they fail to fulfill their payment obligation.

Types of Payment Line Items

The Payment supertype governs the behavior of a variety of line items in Canopy. To find a full list of payment-type line items, check out Line Item Types.

Section Articles

• Minimum Payments
• Payment Splits
• Refunds
• AutoPay
• Late Payments & Webhooks
• Borrower Initiated Payments