Settlement and fees

Standalone definitions of settlements, settled transactions, fee charges, funding models, and reconciliation terms.

These terms describe the records used to connect a merchant's payment activity with bank deposits and processing costs. They use the meanings in the settlement reporting API, which is currently in beta.

ACH Gross

An ACH funding arrangement in which processing fees are billed separately from the merchant's deposit. It is represented by type: Ach and fundingType: Gross. Settled line amounts exclude those separately billed fees, and their sum equals the settlement amount. A failed payout with no disbursement has a zero line amount. See ACH reconciliation.

ACH Net

An ACH funding arrangement in which applicable fees are withheld from the merchant's deposit. It is represented by type: Ach and fundingType: Net. Each settled line's amount reflects any fees withheld from that line; deposit-level fees can further reduce the settlement total. A failed payout can produce a negative line amount equal to the fee for the attempt.

Adjustment

A change to the amount being deposited that is not another sale, such as a reserve hold or transfer. Adjustments help explain why a processor-reported deposit can differ from the total of its transaction lines. Some affect the deposit total without appearing as public transaction lines or billed fee charges. See Reconciliation limits.

Assessment date

The date a daily fee was incurred, exposed as assessmentDate. It is the settlement date for a settlement-linked fee. For a statement or invoice fee and a monthly rollup, it equals chargeDate. When includeInformational=true, the fee listing selects informational components by assessment date. See Fee dates.

Batch

A group of transactions collected by the processor for processing or settlement. A settled card line's batchId identifies its processor batch. One merchant deposit can include transactions from several batches, so the batch identifier belongs to each line rather than to the settlement as a whole.

Billing period and statement period

The span of activity covered by a bill or statement. A fee charge can expose periodStart and periodEnd to identify the activity it covers. These dates can differ from chargeDate, which identifies when the fee is charged. Reconcile statement fees for the same merchant, payment rail, and statement period.

Card Gross

A card funding arrangement in which interchange and discount fees are billed separately instead of being deducted from the deposit. It is represented by type: Card and fundingType: Gross. Reserve holds and transfers can still change the deposit, while card line amounts remain the full settled transaction amounts. "Gross" does not specify when the fees are billed. See Card funding examples.

Card Net

A card funding arrangement in which interchange and discount fees are deducted before payment proceeds are deposited to the merchant. It is represented by type: Card and fundingType: Net. Card line amounts remain the full settled transaction amounts; the fee deductions and reserve adjustments apply to the deposit total. See Card funding examples.

Charge date

The date a fee is or will be charged to the merchant, exposed as chargeDate. The fee listing selects Billed and Pending records by this date. Daily billing uses the assessment date; monthly billing uses the first of the following month. A pending monthly total is not billed merely because that date has arrived, and a statement-only fee is listed only from its month's publication. See Fee dates.

Daily settlement fees

Charges identified from daily settlement activity. The category describes what the merchant is paying for; the funding and billing terms determine how and when it is collected.

The reported charge supplies the amount; these categories do not define a rate or calculation formula. See Transaction and settlement fees.

Component fee

A daily fee included in a monthly rollup. It has status: Informational, source: SettlementLinked, and a parentFeeId identifying the rollup that bills its amount. Its settlement references, when present, let you trace a monthly charge to the underlying deposits and transactions. The component remains informational after its parent is billed. See Monthly rollups and components.

Deposit amount and line amount

A deposit amount is the processor-reported total for a settlement, exposed as the settlement's amount. A line amount is the contribution attributed to one settled transaction, exposed as that line's amount. Card lines are before deposit-level fees and reserves under both funding types. ACH Net lines reflect their own withheld fees. Read the settlement type and fundingType to interpret either amount.

Deposit, disbursement, and payout

A deposit is a transfer of payment proceeds into the merchant's bank account, represented by a settlement record. Disbursement and payout describe the act of sending those proceeds. A payout attempt can fail, in which case no deposit occurs for that attempted transfer even though a reporting line or fee can be recorded.

Discount fee

The month's discount as the card statement's summary prints it, typical for flat-rate pricing. It is exposed as category: DiscountFee and source: StatementOnly, covers the statement period, and is not tied to a specific settled transaction. It includes the discount already withheld from the month's daily deposits, which is also reported day by day as DailyDiscountFee. See Card processing costs on the statement.

Fee breakdown

An optional description of the components that make up a fee charge, exposed as feeBreakdown. Only components supplied by the source report are present:

The components explain the fee charge's amount; they are not additional charges. Read returnFee as a cost of a returned or reversed ACH transaction. A settled line's transactionType: Return has a separate, specific meaning: a failed payout to the merchant.

Fee category

The classification identifying the kind of merchant cost represented by a fee charge, exposed as category. It can be a broad group such as Equipment, a transaction-related fee such as TransactionFee, or a specific statement fee name. The field is an open set of strings, so integrations must preserve and handle unfamiliar values. The description provides the reported fee wording.

Fee charge

A record of a merchant cost for payment processing or related account services. Its status distinguishes a billed charge, a pending monthly total, and an informational component of that total. It states the amount, currency, category, assessment date, and charge date. When applicable, it links to a settlement and a settled transaction. The API identifies it with an mfc_ ID and lists it through GET /fee-charges. See Fee charges.

Fee source

The classification describing where a fee was reported, exposed as source. It does not determine whether the fee has been billed:

A StatementOnly charge has no direct settlement or settled-transaction link. Follow a rollup's components to find their settlement references. A SettlementLinked fee can lack a settlement link if no corresponding deposit is available. See Fee sources.

Fee status

The classification describing whether a fee record has been billed, exposed as status:

includeInformational=true adds pending totals and informational components to the fee listing. Held and reversed entries are excluded from the public endpoints. See Fee status.

Fee unit count

The number of units printed for a fee on a monthly statement or invoice, exposed as feeUnitCount. Units can be transactions, items, batches, or accounts, depending on the charge. Only a valid positive whole-number count is returned; a charge that combines several statement lines reports the sum of their counts. The field is absent when no valid count was reported and on daily fees, monthly rollups, and components. It is separate from componentFeeCount, which counts the daily fee records in a rollup. See Fee counts.

Funding type

The merchant funding arrangement that determines how processing fees affect a deposit. fundingType: Net means applicable fees are withheld from the deposit; Gross means fees are billed separately. Read it with settlement type, because card and ACH line amounts follow different rules. Funding type does not determine the fee billing schedule. See Settlement type and funding type.

Gateway transaction ID

The identifier assigned by the downstream gateway to the payment activity reported on a settled line, exposed as gatewayTransactionId. It helps connect source settlement data with payment records. It is separate from transactionId, which uses the trx_ prefix and can be absent on an unmatched line.

General fee categories

Broad groups used to classify the services or activities for which the merchant is billed:

See Fee categories for their place in fee reporting.

Interchange and passthrough

Interchange and the card-network costs a monthly card statement passes through to the merchant, typical for cost-plus pricing. It is exposed as category: InterchangeAndPassthrough and source: StatementOnly, covers the statement period, and is not tied to a specific settled transaction. It includes the interchange already withheld from the month's daily deposits, which is also reported day by day as DailyInterchangeFee. For flat-rate pricing, the statement's card processing cost is reported as DiscountFee. See Card processing costs on the statement.

Match status

The result of trying to associate a processor-reported settled line with an API transaction, exposed as matchStatus:

An unmatched line still belongs to the settlement and contributes its reported amount. A Refund line is matched to the refund transaction, never to the sale it refunds; a Return line keeps its link to the sale whose payout failed. See Match status.

Monthly fee publication

The point from which a billing month's statement, invoice, and rollup charges are returned by the fee listing. A month is published automatically on the 10th of the following month, at 00:00 US Eastern time. Before then, those StatementOnly records are absent from the response and its totalCount, with no marker. Daily fees and rollup components are never held back. Publication concerns visibility in the API only; it moves no money, and the charge date says when a fee is taken. See When monthly fees become visible.

Monthly rollup

A fee charge that totals daily fees of the same category for one merchant, payment rail, currency, and month. It has source: StatementOnly, the month's period dates, and a componentFeeCount. It starts as Pending and becomes Billed when the corresponding statement or invoice is processed. Its charge date is the first of the following month, and it is listed only once its month is published. GET /fee-charges/{feeChargeId}/components lists its daily fees without a date range. Late fees for an already billed rollup appear in a separate billed correction rollup. See Monthly rollups and components.

netAmount

The deprecated reporting field name replaced by amount. Where still returned, it mirrors amount exactly. Its name does not guarantee an amount after fees: settlement type and funding type determine what the amount includes. See Deprecated: netAmount.

Reconciliation

The process of connecting payment records, settled transaction lines, fee charges, and bank deposits so their amounts and identifiers explain the same activity. In this API, it includes matching a settled line's transactionId to a transaction and checking deposits using the applicable funding rules. Missing card batch data or reserve movements can prevent public line items alone from reproducing a deposit total. See The reporting model.

Reserve hold and reserve transfer

A reserve hold is money retained from merchant proceeds in a reserve balance. A reserve transfer moves money into or out of that balance. These movements can change Card Net and Card Gross deposits, but they are not charges for a service. The public API does not expose them as transaction lines or billed fee charges. See Card reconciliation.

Return

In settled transaction reporting, a Return is a payout attempt that failed to deliver funds to the merchant, for example because the receiving bank account was closed or invalid. The line records the failed attempt and any resulting fee. Its amount can be negative under ACH Net or zero under ACH Gross. An ACH entry the bank returns before any money moves is reported as a Return line in a settlement for that day, with its fee linked through the line. This reporting value describes a failed disbursement; a Refund describes money being returned to a payer after a payment.

Settled transaction

A processor-reported line showing how payment or dispute activity contributes to a merchant deposit. It records the activity's amount and processor identifiers, plus the transaction ID (trx_) when a match is available. Card lines show full settled amounts before deposit-level fees and reserves; ACH lines reflect any fees withheld from that line. Read these records in a settlement's lineItems or through GET /settlements/transactions. See Settled transactions.

Settlement

A record of a processor-reported transfer of payment proceeds to the merchant's bank account. It groups the transaction activity included in one deposit and states the deposit date, currency, total amount, payment rail, and funding type. Fees, refunds, and reserve movements can affect that total. The API identifies a settlement with an stl_ ID and exposes its transaction lines through GET /settlements/{settlementId}. See Settlements.

Settlement date and transaction date

The settlement date is the date the deposit is reported as reaching the merchant's bank account. The transaction date is the date the underlying payment operation was processed, when available. Settlement list endpoints select records by settlement date, so they can include payments made on earlier dates.

Settlement status

The deposit's reporting state, exposed as settlement status. Settled means the deposit has been made to the merchant's bank account. Adjusted is a reserved value and is not currently returned. This field describes a deposit record rather than the processing lifecycle of a payment request.

Settlement transaction type

The activity represented by a settled line, exposed as transactionType. Sale records a sale, Refund records a refund or credit to the payer, Capture records settlement of an earlier authorization, and Return records a failed payout to the merchant, and Chargeback records money taken back from the merchant because the payer's bank returned an ACH payment after funding. New values can be added. See Transaction type for the full definitions.

Settlement type

The payment rail from which a merchant deposit originated, exposed as type: Card or Ach. It is used with fundingType to interpret the deposit and transaction amounts. Card Net and Card Gross are combinations of these fields, not additional settlement type values.

Signed amount

An amount that can be positive, zero, or negative. Settlement deposits and transaction lines use signed amounts so refunds, fees, and adjustments can reduce totals. A negative settlement amount represents a net movement away from the merchant rather than an incoming deposit. See Signed amounts.

Statement fee

A cost billed on the merchant's periodic statement or invoice, such as an account-service or equipment charge. A recognized fee can be reported under its specific name in category. The fee guide gives representative examples grouped by general category. Read the reported description when interpreting an individual charge. See Statement fee examples.

A card statement's charges are reported as printed, one per fee, and include the card fees already withheld from the month's daily deposits. Subtract the period's daily card fees from them to find the month-end deduction. A negative statement charge is a credit against the month's fees, not a refund. See Card statement charges include the daily fees.

Withheld fee

A fee collected by deducting it from payment proceeds before they reach the merchant. The fee is also listed as a fee-charge record for reporting. When a settlement or ACH line amount already reflects that deduction, subtracting the fee again understates the money received.

Zero-movement line

A settled transaction line for activity that disbursed no funds, commonly a failed payout recorded as Return. It remains part of the deposit's reported activity and can still carry a fee. Its amount is zero when fees are billed separately, or negative when its fee is withheld. See Zero-movement lines.

Related

• The reporting model - how the three resources relate
• Settlements - endpoint usage and reconciliation examples
• Fee charges - billing sources and fee categories
• Payments and transactions - the original payment operations