This file is used as part of Lead’s financial reconciliation. If the data is inaccurate, then funding the appropriate accounts is at risk, and the program will run into issues.
For all optional fields where you do not plan to pass through data, please include the header and an empty value.
IDs & Details
| Field | Description | Required | Data Type |
|---|---|---|---|
| client_transaction_id | The unique ID for the transaction. | Required | string |
| balance_id | ID of the balance. Balances need to exist and be uploaded to Lead. | Required | string |
| card_id | The unique ID for this card if the transaction is a card swipe. Cards need to exist and be uploaded to Lead. | Required for transfer_type = card | string |
| client_settlement_group_id | If this transaction is net settled, a unique ID to group all transactions in the net settlement. | Optional | string |
| client_settlement_bank_account_id | ID of the underlying settlement bank account where funds for the balance_id are held. Please reach out to Lead to align on enum | Required for programs with balances held across multiple FBOs (with Lead) and Banks (external to Lead) | enum |
| bin | The BIN for the card associated with this transaction. Please reach out to Lead to align on enum. | Required for transfer_type = card, oct, and aft | enum |
Transaction Information
See Transaction Types for more details on correct signage and value.
| Field | Description | Required | Data Type |
|---|---|---|---|
| amount | Total amount for the transaction. Positive polarity means an increase in balance, and negative polarity means a decrease in balance. When reporting transactions for Credit Balances, this field must equalprincipal_amount + fee_amount+ interest_amount. | Required | For deposit programs, number with a minimum currency decimals (e.g., if currency is USD, value must be at least 2 decimals, 11.500) For credit programs, number currency decimals |
| amount_in_usd | Transaction amount in USD. Polarity should match amount | Required if the program can have non-USD balances | number Minimum 2 decimals, 11.50 or 11.500 |
| currency | currency code for the transaction. 3 letter code, e.g. USD | Required | ISO4217 |
| principal_amount | Applicable to credit products only: Amount for the transaction that affects the principal. When reporting a transaction that originated from a Funding object, this field must equal the sum of all principal.* fields. | Required if balance_id type = credit | number currency decimals |
| fee_amount | Applicable to credit products only: Amount for the transaction that affects the fees. For transactions with type = disbursement, transfer_type = internal_transfer, and funding_id is populated, this value must equal other_fees.borrower_origination_fee_amount on the associated Funding object. | Required if balance_id type = credit | number currency decimals |
| interest_amount | Applicable to credit products only: Amount for the transaction that affects the interest. | Required if balance_id type = credit | number currency decimals |
| rewards_amount | Rewards amount. Positive polarity means an increase in rewards balance, and negative polarity means a decrease in rewards balance. | Required if rewards is offered | number decimal(M, 2) e.g. 11.50 |
| rewards_unit | The unit of the rewards. | Required if rewards_amount is present | enumusdpoints |
| type | Transaction type. | Required | enum |
| transfer_type | Type of transfer rail. | Required for certain transaction types (type) and optional for remainder. See Transaction Types for details. | enum |
| fee_type | Fee type. | Required if type = fee | enum |
| action | Action. | Required | enumappliedreversed |
| description | The description on the customers statement for this transaction. | Required | string |
| transfer_ids | The unique IDs for the related transfer object, if applicable (e.g. the ACH ID or Wire ID or Internal Transfer ID generated by Lead). This is an array of transfer IDs (e.g., the ID for an ACH object generated via the Lead API). If >1 transfer_id, separate using a comma. | Required if transfer_type = ach, wire, international_wire, instant_payment, or internal_transfer and the transaction was initiated via a Lead API. | string ["ach_123", "ach_456"] |
| settlement_date | The expected settlement date of this transaction. - For type = fee, this must be set to T-1. - For type = disbursement and transfer_type = internal_transfer, this must be set to the date when the Funding object transitioned to a posted status (available via the updated_at timestamp on the Funding object).- For transfer_type = card, this must be set to either T or T-1 if the program’s timezone is CT or UTC. If the program’s file window aligns with the card network settlement window, then it must be T. Please provide the date the transaction was included in the raw settlement file (e.g. VSS-115 for Visa or T* files for Mastercard). - For all other types, this can be set to T-7 or future periods. Please use Transactions Updates file if settlement_date has been updated from what was submitted via Transactions. | Required | date YYYY-MM-DD |
| original_transaction_id | The unique ID for the related transaction (if present). This may be relevant for refunds, disputes or returns with original transaction id. | Highly recommended where programs can attribute refunds and disputes to the original transaction | string |
| funding_id | The unique ID of the Funding object that this transaction represents. See Lending and Overdraft page for more details on how and when Funding objects should be reported in the Transactions file. | Required when the transaction record is intended to report a funding object that was posted. In these scenarios, type = disbursement and transfer_type = internal_transfer. | string |
Card Information
| Field | Description | Required | Data Type |
|---|---|---|---|
| card_authorization_amount | Amount authorized at point of sale. Polarity should match amount | Optional (transfer_type must be card if provided) | number currency decimals |
| card_authorization_currency | Currency at point of sale. | Required if card_authorization_amount is present | string |
| card_transaction_effective_at | The posted datetime of the transaction. | Required if 1) transfer_type = card or 2) type = disbursement and transfer_type = no_money_movement and client_settlement_bank_account_id is held at Lead. Must be empty for all other scenarios. | datetime ISO8601 |
| settlement_amount | Amount settled with the card network. Polarity should match amount | Required for transfer_type = card and if network settlement can occur in non-USD currencies | number currency decimals |
| settlement_currency | Card transaction settlement currency. | card and if network settlement can occur in non-USD currencies | string |
| interchange_fee_amount | Amount for the interchange fee of the transaction. | Optional | number currency decimals |
| transaction_fee_amount | Amount for the fee of the transaction. | Optional | number currency decimals |
| acquirer_fee_amount | Amount for the acquirer fee of the transaction. | Optional | number currency decimals |
| card_network | Code identifying the network. | Required for transfer_type = card, oct, and aft. Must be empty for all other transfer_type | enumvisamastercardpulseamexstaraccelmaestrointerlinktabapay |
Merchant Information
| Field | Description | Required | Data Type |
|---|---|---|---|
| merchant_name | Merchant name. | Required for transfer_type = card | string |
| merchant_address_line_1 | Merchant address line 1. | Optional | string |
| merchant_city | Merchant city. | Required for transfer_type = card | string |
| merchant_state | Merchant state. | Highly Recommended for transfer_type = card and merchant_country_code = US | string |
| merchant_country_code | Merchant country code. | Required for transfer_type = card | string ISO3166-1 alpha2 |
| merchant_zip_code | Merchant zip code. | Optional | string |
| mcc | Merchant mcc. | Required for transfer_type = card | string |
Other
| Field | Description | Required | Data Type |
|---|---|---|---|
| generated_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 |
| effective_at | The timestamp of when the related object(s) were polled to collect the information for this record. This is typically a timestamp on one day prior to the generated_at timestamp, since T-1 transactions (effective_at) are reported on T (generated_at). Please provide the date that the transaction affected the end-user’s balance and their available balance has changed (it does not have to have settled yet). | Required | datetime ISO8601 |