> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions File Schema

> Field-level reference for the Transactions file used in Lead's financial reconciliation, including IDs, amounts, types, and posting details.

<Info>
  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.
</Info>

<Check>
  For all optional fields where you do not plan to pass through data, please include the header and an empty value.
</Check>

## 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

<Info>
  See [Transaction Types](/file-integrations/balances-and-transactions/transaction-types) for more details on correct signage and value.
</Info>

| **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 equal`principal_amount` + `fee_amount`+ `interest_amount`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Required                                                                                                                                                                            | For deposit programs, number with a minimum [currency decimals](/file-integrations/file-delivery/currencies) (e.g., if currency is USD, value must be at least 2 decimals, `11.500`)  For credit programs, number [currency decimals](/file-integrations/file-delivery/currencies) |
| 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](/file-integrations/file-delivery/currencies)  for the transaction. 3 letter code, e.g. USD                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Required                                                                                                                                                                            | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html)                                                                                                                                                                                                                        |
| 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](https://docs.lead.bank/api-reference/endpoint/funding/create-a-funding), this field must equal the sum of all `principal.*` fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required if `balance_id` type = `credit`                                                                                                                                            | number<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                       |
| fee\_amount               | Applicable to credit products only: Amount for the transaction that affects the fees.<br />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<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                       |
| interest\_amount          | Applicable to credit products only: Amount for the transaction that affects the interest.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Required if `balance_id` type = `credit`                                                                                                                                            | number<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                       |
| 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                                                                                                                                             | enum<br />`usd`<br />`points`                                                                                                                                                                                                                                                      |
| type                      | Transaction type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required                                                                                                                                                                            | enum                                                                                                                                                                                                                                                                               |
| transfer\_type            | Type of transfer rail.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Required for certain transaction types (`type`) and optional for remainder. See [Transaction Types](/file-integrations/balances-and-transactions/transaction-types) for details.    | enum                                                                                                                                                                                                                                                                               |
| fee\_type                 | Fee type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Required if `type` = `fee`                                                                                                                                                          | enum                                                                                                                                                                                                                                                                               |
| action                    | Action.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Required                                                                                                                                                                            | enum<br />`applied`<br />`reversed`                                                                                                                                                                                                                                                |
| 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 <br />`["ach_123", "ach_456"]`                                                                                                                                                                                                                                              |
| settlement\_date          | The expected settlement date of this transaction.  <br />- For `type` = `fee`, this must be set to T-1. <br />- 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).<br />- 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). <br />- For all other `types`, this can be set to T-7 or future periods.  <br /><br />Please use `Transactions Updates` file if `settlement_date` has been updated from what was submitted via `Transactions`. | Required                                                                                                                                                                            | date <br />`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](/file-integrations/data-flows/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<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                        |
| 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<br />[ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html)                                                     |
| 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<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                        |
| 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<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                        |
| transaction\_fee\_amount         | Amount for the fee of the transaction.                               | Optional                                                                                                                                                                                                       | number<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                        |
| acquirer\_fee\_amount            | Amount for the acquirer fee of the transaction.                      | Optional                                                                                                                                                                                                       | number<br />[currency decimals](/file-integrations/file-delivery/currencies)                                                        |
| card\_network                    | Code identifying the network.                                        | Required for `transfer_type` = `card`, `oct`, and `aft`. Must be empty for all other transfer\_type                                                                                                            | enum<br />`visa`<br />`mastercard`<br />`pulse`<br />`amex`<br />`star`<br />`accel`<br />`maestro`<br />`interlink`<br />`tabapay` |

## 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<br />[ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) |
| 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<br />[ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) |