Introduction

Balance Splits are the core output of Canopy's Payment Pouringordering logic. Using this information you can understand how balances are being impacted by specific Transactions that reduce balances: Payments and Debit Offsets.

This section will describe in detail all characteristics of Balance Splits in Canopy, including allocation types, retroactivity dates, and the transaction that created the balance splits.

📘

Balance Splits vs. Payment Splits

Payment Splits exist in Canopy's system which does a similar job to the Balance Splits feature. Balance Splits was created to add context to the missing information in the Payment Splits endpoint to enable easier reporting on things like revenue, transfers, and reconciliation.

What can be answered with Balance Splits?

The Balance Splits API answers two different questions depending on the transaction that you want to query. This is because some transactions create balances while others decrease them.

What did this payment or offset do?

You have the ability to view the output of Canopy's Payment Pouring logic and how payments and offsets are split into balances owed on an account. The Balance Splits API allows you to investigate each payment to ensure that balances are being paid off in the correct order.

What payments have poured into this balance?

You have the ability to view the portions of payments and offsets that have paid into transactions that have balances (charges, loan principal, interest, fees, credit offsets). The Balance Split API allows you to investigate how a transaction that held a balance has been paid off.

What happened during a specific retroactive event?

This endpoint will allow you to see version history of splits created. Using the concept of "issued at", when something was created, and "effective at", when something effects calculations. This allows your team to reason about how retroactive remediations from reversals effected past calculations and allow you to know when the remediation occurred.

How do I get Balance Splits on a Transaction?

To get Balance Splits of a transactions simply call out endpoint using the example below and replace the variable with the desired account and transaction.

import requests
import json

url = "https://<your_environment>/accounts/<account_id>/transactions/<transaction_id>/balance_splits"

payload = {}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <bearer_token>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Balance Splits Recipe

Balance Split Response Example

    "results": [
        {
            "account_id": "can_5845",
            "balance_split_id": "can_36769",
            "applied_to_transaction_id": "test-658-f",
            "origination_transaction_id": "test-qa-a5ff18d4-18bb-463f-8bc1-0ae5a73c232e",
            "discarded_by_transaction_id": null,
            "issued_at": "2023-01-09T08:11:28-08:00",
            "effective_at": "2023-01-09T08:11:28-08:00",
            "discarded_at": null,
            "amount_cents": -31599,
            "applied_to_transaction_type": "LOAN",
            "applied_to_transaction_super_type": "PRINCIPAL",
            "balance_split_summary": "Split to Loan"
        },

Response Attribute Breakdown

3. "account_id" is the account this balance split belongs to.
4. balance_split_id is the unique ID for this balance split.
5. The applied_to_transaction_idis the transaction which balance was paid by this balance split
6. The origination_transaction_id is the payment or offset ID that created the balance split.
7. The discarded_by_transaction_id is the reversal that discarded the offset or payment. This would indicate that this split has been invalidated by retroactivity.
8. issued_at is the time in which this balance split was created in our system.
9. effective_at is the time in which this balance split effected calculations. This will be an earlier date than the issued at in the event of retroactivity.
10. The amount_cents of a balance splits are always positive. It indicates how much money has been allocated to a specific balance.
11. applied_to_transaction_type and applied_to_transaction_super_type indicate the type of transaction and the allocation balance type for reporting purposes. Using the example above you can learn that this payment split paid off the principal of a loan transaction. For more types view the Transactions Types Document.
12. balance_split_summary is a plain English expression of what this split was applied to. In the example above you can see "Split to Loan" meaning this split paid into a Loan transaction.

Payment Repouring - Retroactivity

As mentioned above, balance splits allows you to easily understand and sort through retroactivity. In the event a series of payments (payment A, payment B, and payment C) are on an account. Then the payment A gets reversed. Canopy "discards" the splits from from payment B and payment C, then "issues" new splits "effective" in the past.

This example highlights an edge case of repouring a payment. If Payment A was never there, Payments B and C would have paid other things, so we "re-pour payments". This means we discard the original Balance Splits and issue new ones so that you can make the proper transfers.

CanopyOS

Balance splits are visible in the transaction detail drawers for each transaction in CanopyOS in the "Balance Splits" component. For a payment or debit offset transaction, this component will display how this balance poured into (i.e. paid off) the appropriate principal, interest, and fee transactions based on the payment pouring order. For a principal, interest, or fee transaction, this component will instead show how payments or offsets have repaid this balance over time.

In this instance, we are viewing the balance splits for a payment which partially paid down first the accrued interest for a loan and a portion of the loan principal.

In order to see the effects of retroactivity, use the "View Other Balance Splits" button at the top right of this component, which will display a dropdown with a list of repour dates. Each repour date will correspond to a retroactive event which caused payments to re-pour. In this instance, a payment reversal on 2024-07-02 caused this payment to repour into older interest line items which the reversed payment had previously paid off.