Introduction

Transactions are the main building blocks of any ledger. Transactions are represented in Canopy as line_items and contain all necessary information used to derive a chronological view of a borrower's activity from a financial accounting point of view. Transactions are only relevant in the context of an account.

This section will describe in detail all characteristics of transactions (line_items) in Canopy, including transaction type and state, relationships between transactions as well as transaction balances and events.

---

Transaction Attributes

Amount

The amount of a transaction is similar to debits and credits in accounting: a positive number indicates an amount owed by the borrower, a negative amount indicates a decrease in the amount owed by a borrower.

Transaction line items record both the original amount this transaction was created (or updated with), and the remaining balance present on that particular transaction as a result of pouring.

Type

The type of a transaction classifies the line item entry based on the borrower's activity.

The main super-types currently in use in Canopy are Interest, Fees, Payments, and Principal. To view the detailed list of types for each transaction super-type access the Line Item Types page.

🗒️

Understanding Super-Types

A super-type is a construct borrowed from Object Oriented Programming where multiple objects can be semantically replaced with one that is either their parent the object hierarchy or their lowest common denominator when analyzed behaviorally. All types under a super-type will behave in the same way when referenced by their super-type (e.g. all PAYMENT sub-types will have a negative amount and pour into fees, interest and principal when created), but individual sub-types can display particularities when handled individually.

As a concrete example of a super-type hierarchy, FEE is a super-type in Canopy that is the conceptual parent of other fee types such as RECURRING_FEE, LATE_FEE, MANUAL_FEE etc.

Status

The status of a transaction reflects wether that transaction has just been submitted, is in the process of executing or has finalized. A full list of Transaction Statuses can be found in the Line Items Statuses page. Different statuses affect the how the transaction is handled by the system in different ways - both from an account balances perspective, as well as from a payment obligations decisioning standpoint.

Intermediary Statuses

Transactions in intermediary statuses allow changes to their attributes through the line item update operation, including modifying the amount (for non-payment transactions).

A common example is Charges. Charges (card transactions / draws on a line of credit) are often initially created with an AUTHORIZED status which signals the transaction being initiated but not yet cleared. From a balances standpoint, authorized charges increase the balance on the account and also affect the total available credit.

Transactions of a payment super type - depending on the payment method used (payment record or payment processor integration) - can start with a PENDING status. This status implies that the payment transaction was created but was not yet confirmed, which marks the moment when the borrower submitted their repayment towards their payment obligation (and no further interest will be accrued or late fees assessed)

(Note for designers - in the picture above the text on the arrows needs to be modified for a generic payment processor - this image is specific for ACH)

🚧

A pending payment will pour (pay existing line items in an account based on Canopy's waterfall logic) in a same manner a valid payment would - at the moment of its creation.

Transactions in intermediary statuses impact most account balances, with some notable exceptions (pending payments affect an account's available credit differently, depending on the pending_pmt_affects_avail_credit product parameter). Further details on how transactions types and statuses count towards each individual account balance can be found in the Balances section of the Account Computational Surfaces page.

Final Statuses

Transactions (line_items) can be created in a final status, or be promoted to a final status through an update operation. Once in a final status, the line item is "locked", not allowing any updates to its amount, state or type.

Positive final statuses include VALID and RETRO_VALID (only relevant in the context of reversal transactions). Transactions in this status are included in most balance calculations on an account and are taken into account when decisioning borrowers' payment obligation fulfillment.

Negative final statuses include INVALID, OFFSET, DECLINED and VOID. Transactions in this status are not included in any balance calculations, and are not taken into account when decisioning borrowers' payment obligation fulfillment.

Timing Information

Every transaction includes relevant timing information, such as:

• when the transaction object was created (created_at)
• when the transaction is being recorded as happening (effective_at)
• for VALID transactions, the time when the transaction was recorded as valid (valid_at)

---

Line Item Relationships

Transactions can be related to one another through parent-child relationships. These relationships are of multiple types: for example, an INTEREST line item can reference the LOAN that generated that particular interest. Another example is a PAYMENT transaction that pours into this INTEREST line item will generate a PAYMENT_SPLIT that will be the child of the payment, at the same time referencing the INTEREST it poured into. Line Item Relationships are retrieved via the Line Item Detail API.

Line Item Splits

Payment Splits get generated whenever a PAYMENT pours into a line item. A split is generated for each line item that payment pours into, and references both the original payment, as well as the transaction it poured into.

Reversal Splits are generated as a result of a Transaction Reversal. These account for differences in balance (interest, fees and/or principal) between the original account and the alternate universe where the transaction did not occur in (where interest & fees could've accrued as a result). Similar to Payment Splits, these line items provide a reference to the original transaction to be reversed, the REVERSAL line item `.

📘

Canopy does not currently surface all line item relationships via REST API. This documentation will be kept up to date as additional access patterns for line item relationships are built.

---

Transaction Metadata

In addition to the attributes mentioned in this article, line items can include a wide variety of metadata. This metadata information is included inside the external_fields attribute as an array of { key:<>, value: <>} objects.

For some issuer processor integrations (e.g. Galileo), card transaction attributes (network, transaction id, type) are included within transaction Metadata by default by prefixing their issuer processor internal attribute name with the issuer processor name (<issuer_processor_name>_<attribute_name>)

Please contact your Canopy Account Manager to discuss arrangements in case you need additional information included in these metadata fields.

Merchant Information

Some transaction types (e.g. charges, refunds, adjustments) originating from an issuer processor may include merchant information under merchant_data. This section includes the timestamp of the transaction as recorded by the issuer processor, merchant name, number and category code. View the GET line items API docs to review the full object details.

---

Transactions and Webhooks

All line items created in Canopy power line_item_create and line_item_update webhook notifications.

---

Related Articles

• Issuer processors
• Payment processors
• Event System