> 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/reporting.md).

# The reporting model

How deposits, settled transaction lines, and fee charges relate - and why amounts and fees are two views of the same money.

{% hint style="warning" %}
**Beta.** Settlement reporting is in beta and requires activation for each merchant. Until your account is enabled, the reporting endpoints return empty results. To ask for access, contact <support@integratedcommerce.io>.

The contract can still change during the beta. Breaking changes are announced with a deprecation period, as `netAmount` was - see [Deprecated: netAmount](#deprecated-netamount).
{% endhint %}

The API reports what a payment processor has settled and deposited to a merchant's bank account, at both the settlement (deposit) and individual-transaction level, plus every fee charged to the merchant - per-transaction settlement fees, daily discount fees, and standalone fees like monthly service, equipment, or one-time setup.

## Three resources

| Resource                                                                    | ID prefix | Definition                                                                                                                                                                                                      |
| --------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Settlement](/glossary/settlement-and-fees.md#settlement)                   | `stl_`    | A record of a processor-reported transfer of payment proceeds to the merchant's bank account. It groups the activity included in one deposit and reports the resulting total.                                   |
| [Settled transaction](/glossary/settlement-and-fees.md#settled-transaction) | -         | A processor-reported line showing how payment or dispute activity contributes to a merchant deposit. It connects the deposit to the original payment activity when a matching transaction is available.         |
| [Fee charge](/glossary/settlement-and-fees.md#fee-charge)                   | `mfc_`    | A record of an individual cost billed to a merchant for payment processing or related account services. It reports what was charged, how much, and when, whether collected from a deposit or billed separately. |

```mermaid
flowchart LR
    S["Settlement (stl_)<br/>deposit amount and funding type"] -->|"contains"| ST["Settled transaction<br/>one line per transaction"]
    S -.->|"settlementId, when linked"| F["Fee charge (mfc_)<br/>per transaction, daily, or standalone"]
    ST -->|"transactionId"| T["Transaction (trx_)<br/>GET /transactions"]
```

### Settlements

A settlement is the deposit-level record used to reconcile payment proceeds with the merchant's bank account. Its `amount` is the processor-reported deposit total after the deductions or adjustments applicable to its funding arrangement. Its date, currency, rail, funding type, and transaction lines explain which activity the deposit represents. Both card and ACH settlements can use `Net` or `Gross` funding.

A single deposit can span several processor batches - for example transactions that queued over a weekend or bank holiday and settled together - so the processor batch number is recorded per line item, not on the settlement.

Listed with `GET /settlements` and retrieved individually with `GET /settlements/{settlementId}`.

### Settled transactions

A settled transaction is the deposit-side record of payment or dispute activity. Its `transactionType` identifies the activity: `Sale`, `Refund`, `Capture`, `Return`, `Dispute`, or `DisputeReversal`. See [Transaction type](/settlement-reporting/settlements.md#transaction-type) for each value's meaning.

Each line states the amount attributed to that activity and carries the processor identifiers used for reconciliation. For Card Net and Card Gross, the line's `amount` is the full settled transaction amount; deposit-level card fees and reserve adjustments are not allocated to individual lines. For ACH, the line's `amount` reflects any fees withheld from that line.

Where possible it is matched to a transaction (`trx_` id) - look up the `transactionId` via `GET /transactions` (for example `?filters=id==trx_...`) for full transaction detail.

Listed by settlement date with `GET /settlements/transactions`.

### Fee charges

A fee charge records a cost the merchant owes for processing payments or using related services, such as a transaction processing fee, monthly account service, or equipment charge. It supplies the category, amount, currency, charge date, and description needed to account for that cost. Fees associated with a settlement link to the relevant deposit through `settlementId`, and per-transaction fees can also identify the settled line through `settledTransaction`.

Listed by charge date with `GET /fee-charges`.

See the [Settlement and fees glossary](/glossary/settlement-and-fees.md) for standalone definitions of funding types, reserves, returns, matching, and the other reporting terms.

## Amounts

All amounts are expressed in the smallest denomination of the currency - cents for USD and CAD.

A settlement's `amount` is the deposit total. Read `type` and `fundingType` together to determine how fees affect it:

| Settlement model | API fields                         | Deposit amount                                                                           |
| ---------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
| Card Net         | `type: Card`, `fundingType: Net`   | After withheld interchange and discount fees, plus signed reserve holds and transfers.   |
| Card Gross       | `type: Card`, `fundingType: Gross` | Before separately billed fees, but after any reserve holds and transfers.                |
| ACH Net          | `type: Ach`, `fundingType: Net`    | Sum of the line amounts after their withheld fees, less any withheld deposit-level fees. |
| ACH Gross        | `type: Ach`, `fundingType: Gross`  | Sum of the line amounts; fees are billed separately.                                     |

Card Net and Card Gross are combinations of these two fields, not additional `type` values. A merchant can have different funding terms for card and ACH settlements. See [Settlements](/settlement-reporting/settlements.md#how-far-the-lines-reconcile-to-the-deposit-total) for the reconciliation rules and examples.

Funding type describes fee withholding. Fee billing dates are separate terms: use each fee charge's `source` and `chargeDate` rather than assuming every gross-funded fee is billed monthly. See [Fee charges](/settlement-reporting/fee-charges.md#card-net-and-card-gross-fees).

{% hint style="warning" %}
Every fee withheld from a deposit is **also** itemized as a fee charge. Do not subtract it from the settlement's `amount` again: the deposit already reflects that deduction. For Card Net, the card line amounts remain before these fees even though the settlement total is after them.
{% endhint %}

### Signed amounts

Amounts are signed. They are normally positive, but negative when:

* Returns or adjustments in a deposit exceed sales, or
* A single line's own withheld fees exceed what it disbursed

Your reconciliation has to handle negative deposits and negative lines. Treating amounts as unsigned, or filtering out negatives, produces totals that do not match the bank.

### Zero-movement lines

Some settled lines move no money at all - most often a payout the provider could not complete, which leaves a line carrying only the fee the attempt cost, reported as a `Return`.

{% hint style="info" %}
These are always returned. They are part of the deposit, and the sum of a deposit's lines is only meaningful with them present. Do not filter them out.
{% endhint %}

## Deprecated: netAmount

{% hint style="danger" %}
`netAmount` is the former name of `amount` and is deprecated. It mirrors `amount` for one month from 2026-08-21 and is then removed. Migrate to `amount`.
{% endhint %}

## Reconciling to a transaction

Settlement reporting tells you what the processor moved; the transaction endpoints tell you what you asked for. To join them, take a settled transaction's `transactionId` and look it up:

```http
GET /transactions?filters=id==trx_01JVGD0BD3D6SRW6A941CPWCJ5
```

See [Retrieving transactions](/payments/transaction-retrieval.md).