> 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/api-reference/settlement-reporting/fee-charges.md). # Fee Charges **Beta.** Settlement reporting is in beta and is not yet available to every merchant. See [Settlement reporting](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/reporting) to ask for access. Fees charged to the merchant outside of any settled transaction (e.g. a monthly service fee, an equipment fee, a one-time setup fee). ## List Fee Charges > Returns a paginated list of merchant fee charges for a given date or date range, based on the charge date.\ > \ > Either \`date\` or \`fromDate\`/\`toDate\` must be provided.\ > \ > The endpoint supports filtering and sorting via the \`filters\` and \`sorts\` parameters (see \[List Transactions]\() for the filter operator table).\ > \ > For one merchant, one rail and one statement period, the \`StatementOnly\` charges - the derived \`InterchangeAndPassthrough\` entry included - sum exactly to the amount the provider's statement says was deducted. Nothing that statement billed is missing from this list, and nothing in it was billed twice.\ > \ > \#### Examples:\ > \- Single day: \`?date=2026-07-01\`\ > \- Fees assigned to monthly billing: \`?fromDate=2026-07-01\&toDate=2026-07-31\&filters=source==StatementOnly\`\ > \- One kind of fee: \`?fromDate=2026-07-01\&toDate=2026-07-31\&filters=category==StatementFee\`\ > \ > Card Net fees that were withheld are already reflected in the deposit amount; do not subtract them again. Card Gross fees are billed separately. Funding type and fee billing schedule are separate terms, so use each fee's \`source\` and \`chargeDate\`. Reserve holds and transfers are not posted fees. See \[Card Net and Card Gross fees]\().
````json {"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"tags":[{"name":"Fee Charges","description":"**Beta.** Settlement reporting is in beta and is not yet available to every merchant. See [Settlement reporting](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/reporting) to ask for access.\n\nFees charged to the merchant outside of any settled transaction (e.g. a monthly service fee, an equipment fee, a one-time setup fee).\n"}],"servers":[{"url":"https://api.omni.integratedcommerce.io/v1"}],"security":[{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"All API requests must be authenticated using an API key. The API key should be included in the `x-api-key` header of each request.\n\n### API Key Format\n\n```\nx-api-key: \n```\n\n### Resource Scope\n\nAn API key grants access only to the resources owned by its merchant. Every resource identifier you supply - transaction IDs, account holder IDs, payment method tokens, subscription IDs, settlement IDs - is resolved within the scope of the merchant that owns the API key.\n\nSupplying an identifier that belongs to a different merchant produces the same not-found response as an identifier that does not exist at all. Responses do not distinguish between the two cases, so a resource ID cannot be used to determine whether it exists under another merchant.\n\n### Environment-Specific Keys\n\nSeparate API keys identify the sandbox and production environments. The base URL for both environments is the same (`https://api.omni.integratedcommerce.io/v1`), but the keys are different.\n\n#### Sandbox Environment\n- Format: `key_test_.`\n- Use this key for development and testing\n\n#### Production Environment\n- Format: `key_live_.`\n- Use this key for live production traffic\n\nSend the complete key, including the secret after the dot. Legacy keys without a dot remain supported until revoked.\n\n### Error Responses\n\nIf authentication fails because of an invalid or missing API key, you will receive a `401 Unauthorized` response. Check the response message for more details.\n\n## Rate Limiting\n\nIf you receive `429 Too Many Requests`, pause before retrying. Honor `Retry-After` when supplied; otherwise use exponential backoff. The API does not guarantee `X-RateLimit-*` headers.\n"}},"parameters":{"ReportDate":{"name":"date","in":"query","required":false,"description":"A single day to report on. Either `date` or at least one of `fromDate`/`toDate` must be provided. When `date` is given it takes precedence and the range is that single day. Send a date in YYYY-MM-DD format.\n","schema":{"type":"string","format":"date"}},"ReportFromDate":{"name":"fromDate","in":"query","required":false,"description":"Inclusive start of the date range. If omitted while `toDate` is given, the range is the single day `toDate`. Send a date in YYYY-MM-DD format.\n","schema":{"type":"string","format":"date"}},"ReportToDate":{"name":"toDate","in":"query","required":false,"description":"Inclusive end of the date range. If omitted while `fromDate` is given, the range is the single day `fromDate`. Send a date in YYYY-MM-DD format.\n","schema":{"type":"string","format":"date"}},"ReportMerchantIds":{"name":"merchantIds","in":"query","required":false,"description":"Comma-separated list of merchant IDs to report on. 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.\n","schema":{"type":"string"}}},"schemas":{"FeeChargesListResponse":{"type":"object","description":"Paginated response containing merchant fee charges","properties":{"totalCount":{"type":"integer","description":"Total number of fee charges that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of fee charges for the current page","items":{"$ref":"#/components/schemas/FeeCharge"}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"FeeCharge":{"type":"object","description":"A record of an individual cost billed to a merchant for payment processing or related account services. It states the amount, currency, category, charge date, and description of that cost, whether collected from a deposit or billed separately. Examples include transaction processing, daily discount, monthly service, equipment, and one-time setup fees. See [Fee charge](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#fee-charge) in the glossary.\n\nA fee associated with a settlement identifies the related deposit through `settlementId`.\n\nPer-transaction fees also carry a `settledTransaction` object mirroring the settled line it applies to (its `gatewayTransactionId`, `matchStatus`, and `transactionId` when matched).\n","properties":{"id":{"type":"string","description":"The fee charge ID, prefixed with `mfc_`."},"category":{"type":"string","description":"What kind of fee this is. An **open set of strings, not a closed enum**. A fee can use a specific fee name or one of the general categories below. New values can be added without an API version change. Treat a value you do not recognise exactly as you treat `Other`: read `description`, which carries the wording the provider printed. Do not fail on an unknown value.\n\n**General fee categories:**\n\n- `MonthlyService` - fees for maintaining the merchant account and related payment services, such as statements, reporting, and gateway services.\n- `PciCompliance` - fees related to Payment Card Industry (PCI) compliance, including compliance services and non-compliance assessments.\n- `OneTimeSetup` - one-time fees for setting up a service, such as an account, gateway, or wireless connection.\n- `NetworkAssessment` - card-network charges passed through to the merchant, such as registration or network participation fees.\n- `Equipment` - fees for payment terminals and related hardware, including charges for equipment that was not returned.\n- `Other` - fees with no more specific classification. Read `description` for the reported fee wording.\n\n**Transaction and settlement fees** (`source` is `SettlementLinked` under daily billing, or `StatementOnly` under monthly billing):\n\n- `DailyDiscountFee` - the daily discount fee assessed against a card settlement.\n- `DailyInterchangeFee` - the daily interchange fee assessed against a card settlement.\n- `TransactionFee` - a per-transaction settlement fee, e.g. an ACH transaction's processing fee.\n- `ReturnFee` - charged when a payout could not be completed; for ACH, typically a closed or invalid bank account, so no money reached the merchant and this fee is the only thing the attempt produced. Its settled line has a `transactionType` of `Return`.\n- `PerSettlementFee` - a flat fee a merchant's pricing applies once to a settlement, independent of what settled in it. Assessed against the deposit rather than any one line, so it carries a `settlementId` and no `settledTransaction`.\n\n**Fees billed on a monthly statement or invoice** (`source` is `StatementOnly`). Representative examples by general category:\n\n- `MonthlyService`: `GatewayService`, `StatementFee`, `WebReportsAlerts`.\n- `PciCompliance`: `PciFee`, `NonComplianceAssessment`, `SaqScanIncomplete`.\n- `OneTimeSetup`: `ApplicationFee`, `GatewaySetup`, `WirelessActivation`.\n- `NetworkAssessment`: `VisaRegistrationFee`, `McRegistrationFee`, `PinBasedDebitNetworkFee`.\n- `Equipment`: `UnreturnedEquipment`.\n- `Other`: an unclassified fee or unrecognized statement wording; read `description`.\n\nA named fee uses its specific value in `category`, such as `GatewayService`, rather than the group name `MonthlyService`. The examples are not an exhaustive list. See [Fee examples by category](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges#fees-billed-on-a-monthly-statement-or-invoice) and use each charge's `description` for its reported wording.\n\n**Derived:**\n\n- `InterchangeAndPassthrough` - interchange and other costs a card statement passes through without naming them individually. Its amount is the statement's total deducted fees minus the sum of named fees. It has `source: StatementOnly`.\n"},"source":{"type":"string","enum":["SettlementLinked","StatementOnly"],"description":"How the fee is reported and billed. Funding type controls whether fees reduce the deposit; the billing schedule separately determines `source` and `chargeDate`.\n\n**SettlementLinked**: a fee associated with a transaction or settlement, charged on its assessment date under daily billing.\n\n**StatementOnly**: a fee billed on a monthly statement or invoice, including transaction and settlement fees scheduled for monthly billing. For fees assessed daily but billed monthly, `chargeDate` is the first of the following month and the assessment date appears in `periodStart` and `periodEnd`. A `StatementOnly` fee can carry a `settlementId`.\n\nCard Net and Card Gross can both have separately reported fee charges. For Card Net, do not deduct a withheld fee from the deposit amount again. For Card Gross, reconcile the separately billed fee using its charge date.\n"},"status":{"type":"string","enum":["Posted","Held","Reversed"],"description":"Whether the entry was charged to the merchant. This endpoint returns only `Posted` fees. Held and reversed entries are excluded, as are reserve movements that do not represent a fee.\n"},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","minimum":0,"description":"The fee amount, smallest denomination."},"chargeDate":{"type":"string","format":"date","description":"The date the fee is charged. For transaction and settlement fees assessed daily, this is the settlement date under daily billing or the first of the following month under monthly billing."},"periodStart":{"type":"string","format":"date","description":"Start of the period the fee covers, for recurring fees."},"periodEnd":{"type":"string","format":"date","description":"End of the period the fee covers, for recurring fees."},"description":{"type":"string","description":"Human-readable description of the fee."},"settlementId":{"type":"string","description":"The related deposit ID, prefixed with stl_, when linked. Can be present for both SettlementLinked and StatementOnly fees; this link alone does not mean the fee was withheld from the deposit."},"settledTransaction":{"$ref":"#/components/schemas/SettledTransactionReference"},"feeBreakdown":{"$ref":"#/components/schemas/SettlementFeeBreakdown"}},"required":["id","category","currency","amount","chargeDate"]},"SettledTransactionReference":{"type":"object","description":"The settled transaction a per-transaction fee applies to, mirroring that transaction's identity. Present only on per-transaction fees. Combine `gatewayTransactionId` with the fee's `settlementId` to locate the settled line via `GET /settlements/{settlementId}`.\n","properties":{"transactionId":{"type":"string","description":"The Fiska transaction ID (`trx_`) of the settled transaction, when that line is matched to a Fiska transaction. Absent when `matchStatus` is `Unmatched`."},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID of the settled transaction. Always present."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"The match status of the settled transaction - the same `matchStatus` reported on that settled transaction.\n\n**Unmatched**: The settled transaction has no identified Fiska transaction; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"}},"required":["gatewayTransactionId","matchStatus"]},"SettlementFeeBreakdown":{"type":"object","description":"Optional breakdown of the components of a fee charge. Only the components that apply to a given fee are present.\n Components are signed integers in minor units; positive values are charges and negative values are credits.\n","properties":{"discountFee":{"type":"integer","description":"Processing/discount fee component, smallest denomination."},"originationFee":{"type":"integer","description":"ACH origination fee, smallest denomination."},"returnFee":{"type":"integer","description":"ACH return fee - charged when a transaction is returned/reversed post-settlement. Smallest denomination."},"interchangeFee":{"type":"integer","description":"Card-network interchange fee, in minor units."},"otherFee":{"type":"integer","description":"Provider-specific catch-all for fee components not otherwise modeled."}}},"Error":{"type":"object","description":"Represents an error that occurred during the request.","properties":{"code":{"type":"integer","enum":[0,1000,1001,2000,2010,2011,2012,2013,2020,2021,2100,2101,2102,2103,2105,2201,2202,2900,2901,2902,2903,3000,3201,3202,3203,3204,3205,3299,3400,3401,3501,3502,3503,4000,4001,4002,4003,4004,6000,6001,6100,6101,6102,6103,6200,6201,6202,6203,6300,6301,6400,6500,6501,6600,6700,6701,6800,6801,6802,6900,6901,6902,9000,9999],"description":"Numeric error code. These are grouped into ranges for easier identification and troubleshooting.\n\n * `0` - Unknown\n * `1000` - AuthenticationGenericError\n * `1001` - MerchantNotAuthorizedForResource\n * `2000` - RequestValidationGenericError\n * `2010` - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.\n * `2011` - InvalidTransactionType\n * `2012` - InvalidAmount\n * `2013` - PaymentMethodUsageRestricted\n * `2020` - InvalidPaymentMethodOwner\n * `2021` - InvalidAccountHolderOwner\n * `2100` - InvalidAccountHolderInformation\n * `2101` - InvalidCountryCode\n * `2102` - InvalidZipCode\n * `2103` - MissingCountryCodeOrZipCode\n * `2105` - InvalidEmailAddress\n * `2201` - MissingUniqueToken\n * `2202` - TransactionDeclinedError\n * `2900` - RequestValidationUnsupportedPayload\n * `2901` - RequestValidationWebhookMissingTypeAndDmnType\n * `2902` - RequestValidationUnsupportedWebhookTokenization\n * `2903` - RequestValidationUnsupportedWebhookType\n * `3000` - UnknownServerGenericError\n * `3201` - InvalidOrExpiredSession\n * `3202` - FailedToCreateSessionInAdapter\n * `3203` - ErrorWhileTokenizingCard\n * `3204` - FailedToLoadThirdPartySdk\n * `3205` - SessionExpired\n * `3299` - JavaScriptError\n * `3400` - ResourceNotReadyError\n * `3401` - TransactionNotCompleteYet\n * `3501` - CouldNotCreateBillingSubscription\n * `3502` - CouldNotCancelBillingSubscription\n * `3503` - BillingSubscriptionInvalidStatus\n * `4000` - ResourceNotFound\n * `4001` - TokenizedCardNotFound\n * `4002` - PaymentMethodNotFound\n * `4003` - AccountHolderNotFound\n * `4004` - BillingSubscriptionNotFound\n * `6000` - SdkGenericError\n * `6001` - SdkJavaScriptError\n * `6100` - SdkSessionLoadFailed\n * `6101` - SdkSessionExpired\n * `6102` - SdkSessionNotInitialized\n * `6103` - SdkEnvironmentMismatch\n * `6200` - SdkCardFieldsInvalid\n * `6201` - SdkCardTokenizationFailed\n * `6202` - SdkCardInitFailed\n * `6203` - SdkCardProcessingFailed\n * `6300` - SdkAchFieldsInvalid\n * `6301` - SdkAchProcessingFailed\n * `6400` - SdkEftProcessingFailed\n * `6500` - SdkWalletError\n * `6501` - SdkWalletProcessingFailed\n * `6600` - SdkThirdPartySdkLoadFailed\n * `6700` - SdkFormValidationFailed\n * `6701` - SdkBillingValidationFailed\n * `6800` - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when `formConfig.enable3DSecure: true`.\n * `6801` - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.\n * `6802` - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.\n * `6900` - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on `transactionResponses[0].responseCode` (10-18) and in `resultText`.\n * `6901` - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.\n * `6902` - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.\n * `9000` - UnhandledGenericError\n * `9999` - MaxErrorCode\n"},"status":{"type":"string","enum":["Completed","Rejected","Interrupted","Unknown"],"description":"Execution status of the request sent to the payment gateway.\n\n * Completed - The request completed successfully.\n * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.\n * Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.\n * Unknown\n"},"message":{"type":"string","description":"Developer-facing error message."},"traceId":{"type":"string","description":"Unique trace identifier for tracking and debugging this request."},"timestamp":{"type":"string","format":"date-time","description":"The timestamp when the error occurred (UTC)."},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Represents a validation error that occurred during the request.","properties":{"code":{"type":"integer","description":"Error code"},"field":{"type":"string","description":"The field with the error"},"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional details about the error"}}}},"responses":{"MissingDateRangeError":{"description":"Bad request - no date parameters were provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnauthorizedError":{"description":"Unauthorized response due to an invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/fee-charges":{"get":{"operationId":"getFeeCharges","summary":"List Fee Charges","description":"Returns a paginated list of merchant fee charges for a given date or date range, based on the charge date.\n\nEither `date` or `fromDate`/`toDate` must be provided.\n\nThe endpoint supports filtering and sorting via the `filters` and `sorts` parameters (see [List Transactions](https://fiska.gitbook.io/omni-payment-api/payments/transaction-retrieval) for the filter operator table).\n\nFor one merchant, one rail and one statement period, the `StatementOnly` charges - the derived `InterchangeAndPassthrough` entry included - sum exactly to the amount the provider's statement says was deducted. Nothing that statement billed is missing from this list, and nothing in it was billed twice.\n\n#### Examples:\n- Single day: `?date=2026-07-01`\n- Fees assigned to monthly billing: `?fromDate=2026-07-01&toDate=2026-07-31&filters=source==StatementOnly`\n- One kind of fee: `?fromDate=2026-07-01&toDate=2026-07-31&filters=category==StatementFee`\n\nCard Net fees that were withheld are already reflected in the deposit amount; do not subtract them again. Card Gross fees are billed separately. Funding type and fee billing schedule are separate terms, so use each fee's `source` and `chargeDate`. Reserve holds and transfers are not posted fees. See [Card Net and Card Gross fees](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges#card-net-and-card-gross-fees).\n","tags":["Fee Charges"],"parameters":[{"$ref":"#/components/parameters/ReportDate"},{"$ref":"#/components/parameters/ReportFromDate"},{"$ref":"#/components/parameters/ReportToDate"},{"$ref":"#/components/parameters/ReportMerchantIds"},{"name":"filters","in":"query","required":false,"description":"Filter criteria in the format: field==value,field!=value\nMultiple filters can be separated by commas.\nAvailable fields: category, source, amount, chargeDate\n","schema":{"type":"string"}},{"name":"sorts","in":"query","required":false,"description":"Sort criteria as comma-separated field names. Prefix a field with `-` for descending order.\nAvailable fields: category, source, amount, chargeDate\n","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number to retrieve (starts at 1).\nFor example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.\n","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"description":"Number of records per page.\nFor example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.\n","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"A successful paginated response containing fee charges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeChargesListResponse"}}}},"400":{"$ref":"#/components/responses/MissingDateRangeError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ````