Transactions
This section describes in detail transaction attributes such as amount, type, status (transition, final & non-final), transaction relationships, transaction metadata, and relevant webhooks.
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
andline_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 asRECURRING_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 referencedLine Item
API endpoint, and not theTransaction
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
Updated 6 months ago