Introduction

Transactions are the main building blocks of any ledger. Transactions 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 in Canopy, including transaction type and state, relationships between transactions, as well as transaction balances and events.

📘

Transactions vs. Line Items

Transactions in Canopy are effectively the same as Line Items in Canopy, to the point where transaction_id and line_item_id can be used interchangeably between the two entities across their APIs. The core differentiator is that transactions provide a lower level detail view of line item records within Canopy, providing more of the raw information to consumers. In the future, transactions will supersede line items -- it is recommended that all development be done on top of the Transaction API's and not the Line Item API's.

---

Transaction Attributes

Amount

The amount of a transaction is similar to debits and credits in accounting: a positive number indicates an increase the the borrower's account balance, a negative amount indicates a decrease in the borrower's account balance.

Transaction 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 transaction entry based on the borrower's activity.

The main super-types currently in use in Canopy are Interest, Fees, Payments, and Principal. To view a detailed list of types for each transaction super-type, access the Transaction 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 whether 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 Transaction 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 transaction 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 transactions 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 can be created in a final status, or be promoted to a final status through an update operation. Once in a final status, the transaction 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 borrower's payment obligation fulfillment.

Negative final statuses include INVALID, DECLINED, REVERSED 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.

Reversed Transactions

Through the creation of reversal transactions, the corresponding transaction being reversed will have it's is_reversed field marked as true to indicate the account balance impacts of the transaction no longer apply towards the account's calculations. These transactions can effectively be ignored from an accounting perspective but can still be queried unless otherwise specified through the filter options of the corresponding API.

Timing Information

Every transaction includes relevant timing information, such as:

• when the transaction object was created (created_at).
• when the transaction was effectively recorded as happening (effective_at).
• when the system became aware of the transaction happening (issued_at). This typically only applies in retroactive contexts where a retroactive correction generates new transactions that can be effective in the past but were not issued until the processing of the retroactive event.
• for VALID transactions, the time when the transaction was recorded as valid (valid_at).

Adjustment Summary

Every PAYMENT_REVERSAL transaction will include an adjustments_summary field containing a summary of the retroactive corrections applied to the account through the final processing of the PAYMENT_REVERSAL transaction. Each (key, value) pair within the object informs users about the transaction_type through the key, the net sum of balance adjustments of the given transaction_type within the corresponding value object and the total instances of the transaction_type also contained within the corresponding value object.

---

Transaction Relationships

Transactions can be related to one another through parent-child relationships. These relationships are of multiple types: for example, an INTEREST transaction can reference the LOAN that generated that particular interest. Another example is a PAYMENT transaction that pours into this INTEREST transaction will generate a PAYMENT_SPLIT that will be the child of the payment, at the same time referencing the INTEREST it poured into. The relationships of a transaction can be found as keys at the root level response on the GET Account Transactions API endpoint and follow a pattern of <relationship_descriptor>_id.

Balance Splits

Balance Splits get generated whenever a transaction with a PAYMENT supertype pours into another transaction. A split is generated for each transaction that balance decreasing transaction pours into, and references both the transaction from which the split originated from and the transaction for which the split was applied to.

---

Transaction Metadata

In addition to the attributes mentioned in this article, transactions 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>)

Merchant Information

📘

Availability of Merchant Data

The described merchant_data field is only available when querying the transaction using the referenced Line Item API endpoint, and not the Transaction endpoint.

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.

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

---

Transactions and Webhooks

All transactions created in Canopy power line_item_create and line_item_update webhook notifications.

---

Related Articles

• Issuer processors
• Payment processors
• Event System