> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/settlement-reporting/settlements.md). # Settlements Deposits, their line items, and how far each type reconciles to the deposit total. {% hint style="warning" %} Settlement reporting is in **beta** and is not yet available to every merchant. See [The reporting model](/settlement-reporting/reporting.md) for how to ask for access. {% endhint %} A settlement (`stl_` id) is one deposit from a settlement provider to the merchant's bank account. ## Endpoints | Operation | Endpoint | | ------------------------------------------------- | --------------------------------- | | List settlements for a date or range | `GET /settlements` | | Get one settlement with its line items | `GET /settlements/{settlementId}` | | List settled transaction lines by settlement date | `GET /settlements/transactions` | ## Date parameters The three list endpoints (`GET /settlements`, `GET /settlements/transactions`, and `GET /fee-charges`) share the same date selection, and **either `date` or `fromDate`/`toDate` must be provided**. | Parameter | Behaviour | | ---------- | -------------------------------------------------------------------------------------------------------------- | | `date` | A single day to report on. When given it takes precedence and the range is that single day. | | `fromDate` | Inclusive start of the date range. If omitted while `toDate` is given, the range is the single day `toDate`. | | `toDate` | Inclusive end of the date range. If omitted while `fromDate` is given, the range is the single day `fromDate`. | Send dates in `YYYY-MM-DD` format. `GET /settlements/{settlementId}` uses the ID and does not require a date. The `merchantIds` parameter accepts a comma-separated list of merchant IDs. Currently, every ID must match the merchant that owns your API key; any other ID is rejected with `401`. Omit it to report on that merchant. ## Listing settlements Returns a paginated list of settlements (bank deposits) for a given date or date range, based on the settlement (deposit) date. Each settlement summarizes one deposit to the merchant's bank account. ```http GET /settlements?date=2026-07-01 GET /settlements?fromDate=2026-07-01&toDate=2026-07-07&filters=type==Ach GET /settlements?date=2026-07-01&sorts=-amount ``` Filter and sort fields: `settlementDate`, `type`, `amount`, `status`. (`netAmount` is accepted as a deprecated alias of `amount` until it is removed.) ### Settlement type and funding type | Field | Values | Meaning | | ------------- | -------------- | ----------------------------------------------------------------------------------------- | | `type` | `Card`, `Ach` | Whether the settlement covers card payments or ACH bank transfers. | | `fundingType` | `Net`, `Gross` | Whether the rail withholds the fees it bills from its deposits, or bills them separately. | Card Net is `type: Card` with `fundingType: Net`. Card Gross is `type: Card` with `fundingType: Gross`. Both combinations also apply to `type: Ach`; the funding terms can differ between card and ACH for the same merchant. {% hint style="info" %} An `amount` is never returned without a `fundingType` in scope, so you never have to look up the merchant's configuration to know what an amount this API returned actually represents. {% endhint %} ## Getting one settlement Returns the details of a single settlement (bank deposit), including its settled-transaction line items. A deposit can span several processor batches, so each line item carries its own `batchId`. ```http GET /settlements/stl_01JZ5F0M3SXA6PDH8YT2M4QWCN ``` Every line item the deposit contains is returned, including any that moved no money, so `lineItems` always matches the settlement's own `transactionCount`. ## How far the lines reconcile to the deposit total Reconcile using both the settlement `type` and `fundingType`. Card line amounts are the full settled transaction amounts in both funding models. Card fees and reserve adjustments apply to the deposit, not to individual transaction lines. {% tabs %} {% tab title="Card / Net" %} The deposit has interchange and discount fees deducted: > sum of card line `amount`s - withheld interchange fees - withheld discount fees + signed reserve holds and transfers = settlement `amount` Refund lines are already negative. Reserve holds reduce the deposit; reserve transfers can increase or decrease it. Fees are itemized by `GET /fee-charges`, typically as `DailyInterchangeFee` and `DailyDiscountFee`, with a `settlementId` and no `settledTransaction`. Do not subtract those fees from the reported settlement `amount` a second time. {% endtab %} {% tab title="Card / Gross" %} Interchange and discount fees are billed separately and do not reduce this deposit: > sum of card line `amount`s + signed reserve holds and transfers = settlement `amount` Gross funding does not mean that the deposit always equals sales less refunds: reserves can still change the amount deposited. Reconcile the separately billed fees using their own `chargeDate`. Monthly billing produces `StatementOnly` fee charges; funding type alone does not determine the billing schedule. {% endtab %} {% tab title="Ach / Net" %} The deposit is built up from its lines, so: > sum of line `amount`s, less any deposit-level fees, equals the settlement's `amount` Deposit-level fees are the ones `GET /fee-charges` returns for this `settlementId` with no `settledTransaction` - a `PerSettlementFee` is charged against the deposit as a whole and belongs to no line. {% endtab %} {% tab title="Ach / Gross" %} No fees are withheld, so: > sum of line `amount`s equals the settlement's `amount` exactly The fees are billed separately. When the billing terms are monthly, they appear as `StatementOnly` [fee charges](/settlement-reporting/fee-charges.md), dated to the month they are taken in rather than to this deposit. {% endtab %} {% endtabs %} {% hint style="warning" %} The card formulas assume all transaction lines are available. The settlement's `amount` is the processor-reported deposit total; card lines can become available later than that total. Reserve holds and transfers are not exposed as transaction lines or posted fee charges. The line items and fee charges therefore may not be sufficient to reconstruct the deposit exactly. Account for these differences before treating a mismatch as a missing payment, and investigate unexplained differences. {% endhint %} ### Card Net and Card Gross example These are alternative funding scenarios, each with two card sale lines of `5000` and `2500` in USD, no refunds, and no reserves. All amounts are in cents. | Component | Card Net | Card Gross | | ------------------------- | --------------- | ------------------------ | | Full settled card amounts | `7500` ($75.00) | `7500` ($75.00) | | Interchange fee | `75`, withheld | `75`, billed separately | | Discount fee | `150`, withheld | `150`, billed separately | | Settlement `amount` | `7275` ($72.75) | `7500` ($75.00) | With an additional reserve hold of `500` ($5.00), the deposits would be `6775` for Card Net and `7000` for Card Gross. The card line amounts would still be `5000` and `2500` in both cases. A reserve hold is a movement of funds, not a fee, so it is not included in the posted fee-charge list. The API reference includes separate Card Net and Card Gross response examples for `GET /settlements`, `GET /settlements/{settlementId}`, and `GET /settlements/transactions`. ## Settled transactions Returns a paginated list of settled transactions for a given date or date range, based on the settlement date. Each item is enriched with the summary of the settlement it belongs to. ```http GET /settlements/transactions?date=2026-07-01 GET /settlements/transactions?fromDate=2026-07-01&toDate=2026-07-07&filters=matchStatus==Unmatched GET /settlements/transactions?date=2026-07-01&sorts=-amount ``` Filter and sort fields: `settlementDate`, `matchStatus`, `amount`. ### Transaction type The `transactionType` field identifies the activity represented by a settled line. It appears in both `GET /settlements/{settlementId}` under `lineItems` and `GET /settlements/transactions` under `items`. | Value | Meaning | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Sale` | A sale that deposited funds to the merchant. | | `Refund` | A refund or credit returned to the cardholder or payer. It reduces the deposit. | | `Capture` | Settlement of a previously authorized transaction. | | `Return` | A payout the processor could not deliver to the merchant, such as an ACH payout to a closed or invalid bank account. When nothing was disbursed, its line amount is zero under gross funding or negative for any fee withheld under net funding. | | `Dispute` | A debit for a disputed payment, recorded when the payment processor first receives the dispute or when the final decision favors the payer. | | `DisputeReversal` | A credit returning disputed funds to the merchant when the merchant challenges the dispute. | `Dispute` and `DisputeReversal` apply to all payment methods. ### Match status Where possible, a settled line is matched to a Fiska transaction (`trx_` id). | Value | Meaning | | ----------------- | ------------------------------------------------------------------------------------------ | | `Unmatched` | No Fiska transaction has been identified for this settled line; `transactionId` is absent. | | `Matched` | Automatically matched to a Fiska transaction. | | `ManuallyMatched` | Matched to a Fiska transaction by manual reconciliation. | For lines with a `transactionId`, look the ID up via `GET /transactions` for full transaction detail: ```http GET /transactions?filters=id==trx_01JVGD0BD3D6SRW6A941CPWCJ5 ``` {% hint style="info" %} Handle `Unmatched` lines rather than dropping them. They are still real money in the deposit; they simply have no Fiska transaction identified yet. Filtering them out makes your totals disagree with the bank. {% endhint %} ## Related * [The reporting model](/settlement-reporting/reporting.md) - signed amounts, zero-movement lines, and the `netAmount` deprecation * [Fee charges](/settlement-reporting/fee-charges.md)