Fee charges

Every fee charged to the merchant, whether withheld from a deposit or billed monthly.

A fee charge (mfc_ id) records a merchant cost. Its status tells you whether it is billed, a pending monthly total, or an informational component of that total. A fee associated with a deposit carries a settlementId; a per-transaction fee also identifies the settled line through settledTransaction. Monthly totals and standalone fees have neither link.

Amounts are signed integers in the smallest currency unit. A positive amount is a charge; a negative amount is money returned to the merchant.

GET /fee-charges?date=2026-07-01
GET /fee-charges?fromDate=2026-07-01&toDate=2026-07-31&filters=source==StatementOnly

By default, the endpoint returns only Billed fees, selected by chargeDate. Add includeInformational=true to also return Pending monthly totals by chargeDate and Informational component fees by assessmentDate. The flag defaults to false; an invalid boolean value returns 400.

Statement, invoice, and monthly rollup charges are returned only once their billing month is published, on the 10th of the following month. See When monthly fees become visible.

Filter and sort fields: category, source, amount, chargeDate, assessmentDate. parentFeeId is an additional filter for components of a particular monthly total. It is not a sort field. The endpoint does not support a status filter; when requesting informational records, separate the statuses in your application.

The date parameters are the same as the settlement endpoints. Supply date or at least one of fromDate/toDate. Results are paginated with page and pageSize; read every page when calculating a total.

When monthly fees become visible

Every fee with source: StatementOnly - a statement fee, an invoice fee, or a monthly rollup - is absent from the listing until its billing month is published. A month is published automatically on the 10th of the following month, at 00:00 US Eastern time. Nothing in the response marks a withheld fee: until then, the record is not returned and not counted in totalCount. Publication only makes the records visible; it moves no money, and chargeDate still says when a fee is taken.

Daily fees (source: SettlementLinked), including the informational components of a rollup, are never held back, and GET /fee-charges/{feeChargeId}/components is not affected. You can follow a month's daily detail as it accrues, and read the statement charges from the publication day.

For example, the August 2026 statement charges carry chargeDate: 2026-09-01. A query for September 1 returns them from September 10. Daily fees assessed in August are returned throughout September.

A statement or invoice can be reprocessed until its month is published, which replaces its charges with new records and new IDs. An early publication can also be withdrawn before the 10th, in which case charges you read earlier disappear and return with new IDs. Treat statement and rollup IDs as final from the automatic publication day.

status

Held and reversed entries, including reserve movements that are not fees, are excluded from the public endpoints. Only Billed fees belong in a billed total.

Dates and periods

For example, an informational fee assessed on July 15 has assessmentDate: 2026-07-15 and chargeDate: 2026-08-01. Its monthly total has both dates set to August 1 and covers July 1 through July 31.

With includeInformational=true, a July query returns the July components throughout July. Request August 1 to see their monthly total, whether it is still Pending or has become Billed; it is returned from August 10, when July is published. A single query can therefore include billed fees from an earlier period and components assessed during the requested period. Do not add those statuses together.

Monthly rollups and components

A monthly rollup is a fee charge that totals daily fees of the same category for one merchant, payment rail, currency, and month. Its source is StatementOnly. It starts as Pending and becomes Billed when the corresponding monthly statement or invoice is processed. Reaching the charge date alone does not make it billed. The rollup itself is listed only once its month is published; its components are listed throughout the month.

Each daily component has source: SettlementLinked, status: Informational, and a parentFeeId pointing to its rollup. A component retains its settlement and settled-transaction references when available. It remains informational after the rollup is billed.

feeUnitCount and componentFeeCount measure different things. Neither can be calculated from the other. A printed count of zero, a negative or fractional value, or a value above 2147483647 is not returned as feeUnitCount.

Once a rollup is billed, late fees produce a separate billed correction rollup with its own ID, the original period, and the original billing date. Include those additional records when reviewing that period again.

List a rollup's components

GET /fee-charges/mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH/components

GET /fee-charges/{feeChargeId}/components returns a paginated list of the component fees. It needs neither date parameters nor includeInformational. It accepts the same page, pageSize, sorts, and filters as the fee listing. The default order is ascending assessmentDate, then fee ID. A supplied sort replaces that order.

A fee you own with no components returns 200 with an empty page. A malformed fee ID returns 400; an unknown ID or another merchant's ID returns 404. Reporting access is required, as for the other reporting endpoints.

You can also select components through the dated listing:

GET /fee-charges?fromDate=2026-07-01&toDate=2026-07-31&includeInformational=true&filters=parentFeeId==mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH

This query selects components by their assessment dates. Without includeInformational=true, the default billed-only listing excludes them. An invalid or unknown parentFeeId equality filter returns an empty page.

source: where the fee came from

source identifies the origin of a fee, not when it is billed. Use status and chargeDate for billing. A SettlementLinked fee can have no settlement link when no corresponding deposit is available. An ACH per-settlement fee reported before its day's deposit gains its settlementId once that deposit is reported, so re-read a fee that had none.

Card Net and Card Gross fees

Funding type and fee billing schedule are separate terms. Do not infer a fee's source or chargeDate from fundingType alone. A settlement link identifies a fee's origin; it does not by itself mean that the fee was withheld from that deposit. Reserve holds and transfers can change deposits in both card funding models, but they are not billed fees and are excluded from this endpoint.

See the Card Net and Card Gross example for the amounts on the deposit and its transaction lines.

Card statement charges include the daily fees

A monthly card statement is reported as it is printed: one StatementOnly charge per fee on the statement, with the fee's name in category, its wording in description, and the sum of its statement lines in amount. The API derives nothing and nets nothing.

The statement's discount and interchange figures cover the whole month, including the amounts already withheld from the month's daily deposits. Those daily amounts are also reported, as SettlementLinked charges such as DailyInterchangeFee and DailyDiscountFee, each with its settlement date. The API does not subtract them from the statement charges. It is up to you to deduct the period's daily card fees from the monthly charges.

A worked example for July 2026, Card Net, in cents:

The month's card cost is the statement total: 79273 ($792.73). The month-end deduction is the statement total less the daily fees: 79273 - 75200 = 4073 ($40.73). Adding the daily fees to the statement total counts 75200 twice.

A statement charge can be negative. It is a credit the statement applies against the month's fees, not a refund to a customer. A fee whose statement lines net to zero is not reported.

ACH invoices are different. An invoice line that restates daily transaction, return, or per-settlement fees does not create an additional charge, because those amounts are already reported by the daily fees or their monthly rollups.

category: an open set, not a closed enum

General fee categories

These categories describe broad groups of fees. Read description for the wording of the individual charge.

Transaction and settlement fees

Daily fees have source: SettlementLinked. Under monthly billing, their StatementOnly rollups use the same categories and a later chargeDate.

Fees billed on a monthly statement or invoice

These fees have source: StatementOnly. The examples below show specific fee names grouped under the general categories. A named fee uses its specific value in category, such as GatewayService, rather than the group name MonthlyService.

These are representative examples. The fees charged depend on the merchant's pricing and services. Read each charge's description for the reported wording and chargeDate for when it is billed.

An ACH invoice line that restates daily transaction, return, or per-settlement fees does not create an additional billed charge. Those amounts are already represented by the daily fees or their monthly rollups. Named card statement fees can include per-transaction charges; these remain statement fees.

Card processing costs on the statement

Both have source: StatementOnly and cover the statement period. They are not assessed per transaction and carry no settlement link. Each includes what the month's daily deposits already withheld; see Card statement charges include the daily fees. DiscountFee differs from DailyDiscountFee, which is one day's discount assessed against a card settlement.

Read category to identify the type and description for its wording. Description text can vary; do not use it as an identifier. Changes to pricing or wording do not relabel previously reported fees.

Do not double-count

Related

• The reporting model
• Settlements