Balances File
All Balances
| Validation | Description |
|---|---|
| All Balances with a non-terminal status must be reported daily | All Balances that exist in a non-terminal status on T-1 must be reported in the Balance file submitted on day T. The Subledger Balance object created via the API and the Balance record in the file represent the same underlying object — meaning this validation applies to any Subledger Balance objects. Subledger Balance objects created on T-1 must be included in day T’s Balance file. A newly created Subledger Balance with a zero-dollar balance must still appear in the next day’s file. Terminal statuses are closed and receivable_transferred. |
| New Balances can only be created either via API or files, but not both | For programs that use the Subledger Balance API to create Balances, only the API can be used to create new Balances. Lead validates that no new, unrecognized balances appear in a Balance file. For programs that use the Balance file to create Balances, only the file can be used to create new Balances. For these use cases, unrecognized balances can appear in a Balance file, and we treat these as new Balance objects to be created in Lead’s system. |
Balance file account_id must match the API record | Because they represent the same underlying object, Lead validates that the account_id associated with a given Balance in a Balance file matches the account_id that was used to create the Balance via the Subledger Balance API. |
Deposit Balance
See Balance Reconciliation and Examples for specific examples.
| Validation | Description |
|---|---|
balance on t = balance on t-1 + daily_activity on t | daily_activity on t = sum(transactions.amount) where transactions.type not in (interest_accrued,charge_off_recovery,dispute_won) |
rewards_balance on t = rewards_balance on t-1 + daily_rewards_activity on t | daily_rewards_activity on t = sum(transactions.rewards_amount) where transactions.type in (rewards_earned, rewards_spent, rewards_redeemed,debit, refund,credit) |
interest_accrued_balance on t = interest_accrued_balance on t-1 + daily_interest_activity on t | daily_interest_activity on t = transactions.amount where transactions.type=interest_accrued - transactions.amount where transactions.type= interest_paid |
dispute_balance on t = dispute_balance on t-1 + daily_dispute_activity on t | daily_dispute_activity on t = sum (amount) where transactions.type in (dispute_provisional, dispute_won, dispute_lost) |
charge_off_balance on t = charge_off_balance on t-1 + daily_charge_off_activity on t | daily_charge_off_activity on t = sum (transactions.amount) where transactions.typein (charge_off, charge_off_recovery) |
Credit Balance
See Balance Reconciliation and Examples for specific examples.
| Validation | Description |
|---|---|
balance on t = balance on t-1 + daily_activity on t | daily_activity on t = sum(transactions.amount) where transactions.type not in (charge_off_recovery,dispute_won) |
any balance across balance, dispute_balance, past_due_balance, charge_off_balance will have the following validations: | *balance = *principal + *interest + *fees |
outstanding_principal on t = outstanding_principal on t-1 + daily_principal_activity on t | daily_principal_activity on t = sum (transactions.principal_amount) where transactions.type not in (fee,interest_accrued,charge_off_recovery,dispute_won) |
outstanding_fees on t = outstanding_fees on t-1 + daily_fees_activity on t | daily_fees_activity on t = sum(transactions.fee_amount) where transactions.type not in (disbursement,interest_accrued,charge_off_recovery,dispute_won) |
outstanding_interest on t = outstanding_interest on t-1 + daily_interest_activity on t | daily_interest_activity on t = sum(transactions.interest_amount) where transactions.type not in (disbursement,fee,charge_off_recovery,dispute_won) |
rewards_balance on t = rewards_balance on t-1 + daily_rewards_activity on t | daily_rewards_activity on t = sum(transactions.rewards_amount) where transactions.type in (rewards_earned, rewards_spent, rewards_redeemed,disbursement, refund,client_credit) |
dispute_balance on t = dispute_balance on t-1 + daily_dispute_activity on t | daily_dispute_activity on t = -transactions.amount where transactions.type = dispute_provisional+ transactions.amount where transactions.type = dispute_won - transactions.amount where transactions.type = dispute_lost (the same logic applies for dispute_principal, dispute_fees, dispute_interest) |
charge_off_balance on t = charge_off_balance on t-1 + daily_charge_off_activity on t | daily_charge_off_activity on t = - transactions.amount where transactions.type = charge_off + transactions.amount where transactions.type = charge_off_recovery (the same logic applies for charge_off_principal, charge_off_fees, charge_off_interest) |
past_due_balance<=balance | past_due_principal<=outstanding_principal;past_due_fees<=outstanding_fees ;past_due_interest<=outstanding_interestIf a credit balance is both past due and charged off, the amount should only be included in charge_off_balance and not in past_due_balance. |
| Balances with processing Funding objects cannot be closed | Lead validates that any Balance being reported as closed in a Balance file does not have associated Funding objects in a processing status. This ensures that Funding objects that eventually post can be reported as disbursement transactions, which would not be possible if the Balance has a closed status. |
No transactions can be reported after receivable_transferred | Lead validates that no transactions are reported on a balance after its status has been set to receivable_transferred. |
Only credit balances can be set to receivable_transferred | The receivable_transferred status is not valid for deposit balances. |
Transactions File
| Validation | Description |
|---|---|
| All transaction IDs must be unique | All transaction IDs in this file are unique and have never been seen in a Transactions file before. This validation is how Lead ensures that no duplicate transactions are accidentally reported. |
| All posted Fundings from T-1 must be reported | Lead validates that any Funding objects that transitioned to a posted status during T-1 (as measured by your program’s definition of a 24-hour period) are reported in the Transaction file. |
| Reported Funding objects must be in a posted status | Lead validates that any Funding object reported in a Transaction file (represented as a Transaction record with type = disbursement) is in a posted status. This prevents a case where a pending Funding object is reported prematurely. |
balance_id on the Transaction and Funding object must match | Lead validates that any disbursement transaction reported with a funding_id has a balance_id that matches the subledger_balance_id on the Funding object. |
Funding effective_at must match the posted timestamp | Lead validates that all Funding objects reported have an effective_at date that matches when the Funding object transitioned to a posted status. For example, if a Funding object transitioned to a posted status anytime during the 2025-12-31 24-hour period, the reported effective_at date must be set to 2025-12-31. |
No duplicate funding_id values | Lead validates that any funding_id reported in a Transaction file has not previously been reported and successfully processed. This prevents a case where a duplicate receivable is created for a single Funding request. |
fee_amount on the disbursement transaction must match Funding borrower_origination_fee_amount | For funding disbursement transactions, Lead validates that fee_amount equals other_fees.borrower_origination_fee_amount on the associated Funding object. A mismatch returns a funding_fee_amount_mismatch error. |