# 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](https://docs.canopyservicing.com/v2/docs/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](https://docs.canopyservicing.com/v2/docs/payment-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](https://docs.canopyservicing.com/v2/docs/transaction-types) page. > ### Understanding Super-Types > A [super-type](https://www.sitepoint.com/the-layer-supertype-pattern-encapsulating-common-implementation-in-multi-tiered-systems/) 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](https://docs.canopyservicing.com/v2/docs/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](https://docs.canopyservicing.com/v2/reference/editlineitem) 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](https://docs.canopyservicing.com/v2/docs/payments) used (payment record or [payment processor integration](https://docs.canopyservicing.com/v2/docs/payment-processor)) - 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). > 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](https://docs.canopyservicing.com/v2/reference/createproduct) 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](https://dash.readme.com/project/canopy-api/v2/docs/computational-surface). ### Final Statuses Transactions can be [created](https://docs.canopyservicing.com/v2/reference/createaccountcharge) in a final status, or be promoted to a final status through an [update](https://docs.canopyservicing.com/v2/reference/editlineitem) 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](https://docs.canopyservicing.com/v2/reference/createaccountpaymentreversal) 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](https://docs.canopyservicing.com/v2/reference/createaccountpaymentreversal) 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 **object** was updated (`updated_at`). This includes changes to the transaction such as the `balance_cents` changing, the transaction being reversed, the transaction's `transaction_status` changing, etc. - 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](https://docs.canopyservicing.com/reference/getaccounttransactions) endpoint and follow a pattern of `_id`. ## Balance Splits **[Balance Splits](https://docs.canopyservicing.com/v2/docs/payment-split)** 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 (`_`) ## 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](https://en.wikipedia.org/wiki/Merchant_category_code). View the [GET line items API docs](https://docs.canopyservicing.com/v2/reference/getaccountlineitem) 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.