Fee Charges

Beta. Settlement reporting requires access to be enabled. Without it, a valid merchant API key receives 403 Forbidden. See Settlement 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

GET/fee-charges

Returns a paginated list of merchant fee charges. By default, only Billed fees are returned, selected by chargeDate.

Add includeInformational=true to also return Pending monthly rollups by chargeDate and Informational daily components by assessmentDate. Supply date or at least one of fromDate/toDate.

Monthly rollups have source: StatementOnly and no direct settlement link. Their informational components have source: SettlementLinked, a parentFeeId, and settlement references when available. A pending rollup becomes billed when the corresponding statement or invoice is processed, not merely when its charge date arrives. Late fees for an already billed rollup appear in a separate billed correction rollup with the original period and billing date.

Statement, invoice, and rollup charges (source: StatementOnly) are returned only once their billing month is published: on the 10th of the following month. Publication only makes the records visible; it moves no money. Until then they are absent from the items and from totalCount, with no marker. Daily fees and rollup components are never held back, and neither is the components endpoint. Until a month is published its statement or invoice can be reprocessed, which replaces its charges and their IDs. See When monthly fees become visible.

Only Billed records belong in billed totals. Do not add a rollup and its components together. Read every result page when calculating totals. Card Net fees already withheld are reflected in the deposit amount; do not subtract them again. A card statement's charges include the card fees already withheld from the month's daily deposits; do not add the daily fees to the statement charges, and deduct them from the statement charges to find the month-end deduction. Funding type and fee billing schedule are separate terms. See Fee charges.

Examples:

Billed fees for one day: ?date=2026-08-01
Billed monthly fees and rollups, from August 10: ?date=2026-08-01&filters=source==StatementOnly
July components: ?fromDate=2026-07-01&toDate=2026-07-31&includeInformational=true&filters=parentFeeId==mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH
Pending or billed July rollups, from August 10: ?date=2026-08-01&includeInformational=true&filters=source==StatementOnly

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

Parameters

Name	In	Type	Description
`date`	query	string (date)	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.
`fromDate`	query	string (date)	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.
`toDate`	query	string (date)	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.
`merchantIds`	query	string	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.
`includeInformational`	query	boolean	Also include Pending monthly rollups by chargeDate and Informational components by assessmentDate. Held and reversed entries remain excluded, and so does every StatementOnly record of a billing month that is not yet published. An invalid boolean returns 400.
`filters`	query	string	Filter criteria as comma-separated expressions. Fields: category, source, amount, chargeDate, assessmentDate, parentFeeId. Category accepts general categories and specific fee names. parentFeeId selects components of a rollup; use includeInformational=true and their assessment dates. A malformed, unknown, or other merchant's parentFeeId equality filter returns an empty page. Status is not a filter field.
`sorts`	query	string	Comma-separated field names; prefix with - for descending order. Fields: category, source, amount, chargeDate, assessmentDate. parentFeeId and status are not sort fields.
`page`	query	integer	Page number to retrieve (starts at 1). For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.
`pageSize`	query	integer	Number of records per page. For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.

Responses

200

A successful paginated response containing fee charges

application/json · FeeChargesListResponse

totalCount integer required

Total number of fee charges that match the filter criteria

Example: 2

page integer required

The current page number (starts at 1)

Example: 1

pageSize integer required

Number of items per page

Example: 10

totalPages integer required

Total number of pages available

Example: 1

hasNextPage boolean required

True if there are more pages of results available

Example: false

hasPreviousPage boolean required

True if there are previous pages of results available

Example: false

items array of FeeCharge required

Array of fee charges for the current page

Child attributes

id string required

The fee charge ID, prefixed with mfc_.

Example: "mfc_01JZ5G4K8WQT2XB7RD9NVMC3EH"

category string required

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.

General fee categories:

MonthlyService - fees for maintaining the merchant account and related payment services, such as statements, reporting, and gateway services.
PciCompliance - fees related to Payment Card Industry (PCI) compliance, including compliance services and non-compliance assessments.
OneTimeSetup - one-time fees for setting up a service, such as an account, gateway, or wireless connection.
NetworkAssessment - card-network charges passed through to the merchant, such as registration or network participation fees.
Equipment - fees for payment terminals and related hardware, including charges for equipment that was not returned.
TransactionFee - per-transaction processing costs, including fees assessed on individual settled transactions and per-item or authorization charges billed on a monthly card statement.
Other - fees with no more specific classification. Read description for the reported fee wording.

Transaction and settlement fees (daily fees have source: SettlementLinked; under monthly billing their rollups have source: StatementOnly):

DailyDiscountFee - the daily discount fee assessed against a card settlement.
DailyInterchangeFee - the daily interchange fee assessed against a card settlement.
TransactionFee - a per-transaction settlement fee, e.g. an ACH transaction's processing fee.
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. The fee of an ACH entry the bank returned is reported as ReturnFee when the processor reports it as a return fee, otherwise as TransactionFee.
ChargebackFee - charged when the payer's bank returns an ACH payment after the funds reached the merchant. description is Chargeback fee. Its settledTransaction is the Chargeback line on the deposit of the day the return settled, not the sale's line. Under monthly billing it rolls up under its own ChargebackFee parent.
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.

Fees billed on a monthly statement or invoice (source is StatementOnly). Representative examples by general category:

MonthlyService: GatewayService, StatementFee, WebReportsAlerts.
PciCompliance: PciFee, NonComplianceAssessment, SaqScanIncomplete.
OneTimeSetup: ApplicationFee, GatewaySetup, WirelessActivation.
NetworkAssessment: VisaRegistrationFee, McRegistrationFee, PinBasedDebitNetworkFee.
Equipment: UnreturnedEquipment.
TransactionFee: per-item or authorization charges classified as per-transaction. A named charge uses its specific fee name in category.
Other: an unclassified fee or unrecognized statement wording; read description.

A 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 and use each charge's description for its reported wording.

Card processing costs on the statement:

InterchangeAndPassthrough - interchange and the card-network costs the monthly card statement passes through to the merchant, read from the statement lines reported under this category. Typical for cost-plus pricing.
DiscountFee - the month's discount as the card statement's summary prints it. Typical for flat-rate pricing.

Both have source: StatementOnly, cover the statement period, and are not tied to a specific settled transaction. DiscountFee differs from DailyDiscountFee, which is one day's discount assessed against a card settlement.

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, which are also reported as SettlementLinked daily fees. The API does not subtract them. Deduct the period's daily card fees from the statement charges to find the month-end deduction, and do not add the two together. See Card statement charges include the daily fees.

Description wording can vary; use category as the identifier. Changes to pricing or wording do not relabel previously reported fees.

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

Example: "AuthorizationFee"

source string required

Where the fee was reported, independently of its billing schedule.

SettlementLinked: a fee from daily settlement activity. It is billed directly under daily billing or is an informational component under monthly billing. Settlement references are present when available; a fee can lack a link if no corresponding deposit is available.

StatementOnly: a fee from a monthly statement or invoice, or a monthly rollup of daily fees. It has no direct settlement or settled-transaction link. Follow a rollup's components for those references.

Use status and chargeDate for billing. Funding type controls whether fees reduce the deposit. Do not deduct a withheld fee from a deposit amount that already includes that deduction.

Allowed: SettlementLinked, StatementOnly

Example: "StatementOnly"

status string required

Billed fees are charged to the merchant and are the only records returned by the default fee listing.

With includeInformational=true, the listing also returns Pending monthly rollups, which are still accumulating or awaiting their statement or invoice, and Informational daily components, whose amounts are billed through their parent rollup. The components endpoint returns the informational components directly. Only Billed records belong in billed totals. Held and reversed entries are excluded from the public endpoints.

Whatever its status, a StatementOnly record is absent from the listing until its billing month is published, on the 10th of the following month or earlier for the account. Nothing in the response marks the difference; the record appears from that day.

Allowed: Billed, Pending, Informational

Example: "Billed"

currency string required

Allowed: USD, CAD

Example: "USD"

amount integer (int64) required

Signed amount in the smallest currency unit. Positive is a charge; negative is money returned to the merchant. A pending rollup amount can change as components arrive. A negative statement charge is a credit the statement applies against the month's fees, not a refund; a statement fee whose lines net to zero is not reported.

Example: 2995

assessmentDate string (date) required

The settlement date for a daily fee. For a statement or invoice fee and a rollup, it equals chargeDate. Informational fees are selected by this date when includeInformational=true.

Example: "2026-07-01"

chargeDate string (date) required

The date a fee is or will be charged. Daily billing uses assessmentDate; monthly billing uses the first of the following month. Billed and Pending fees are selected by this date. Reaching this date alone does not make a pending rollup billed. A StatementOnly fee is listed only from the publication day of its charge month, the 10th.

Example: "2026-07-01"

periodStart string (date)

Start of the period covered by a statement or invoice fee or monthly rollup. Absent on settlement-linked fees, including informational components.

Example: "2026-06-01"

periodEnd string (date)

End of the period covered by a statement or invoice fee or monthly rollup. Absent on settlement-linked fees, including informational components.

Example: "2026-06-30"

parentFeeId string

The monthly rollup's mfc_ ID on an informational component. Absent on other fees. GET /fee-charges/{feeChargeId}/components lists the rollup's components.

pattern "^mfc_[0-9A-HJKMNP-TV-Z]{26}$"

Example: "mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH"

componentFeeCount integer required

Number of daily component fees in a rollup. Always returned; 0 on other fees. It is not feeUnitCount.

min 0

Example: 10

feeUnitCount integer (int32)

Positive whole-number count printed for a fee on a monthly statement or invoice, such as transactions, items, batches, or accounts. A charge that combines several statement lines reports the sum of their counts. Absent when no valid count was reported, and on daily fees, rollups, and components. Zero, negative, fractional, and out-of-range counts are omitted. Independent of componentFeeCount.

min 1 · max 2147483647

Example: 100

description string

Human-readable fee wording. It can vary; use category to identify the fee type.

Example: "Monthly service fee - June 2026"

settlementId string

The related deposit ID, prefixed with stl_, when available on a SettlementLinked fee. Absent on StatementOnly fees and rollups. A link identifies the origin of the fee, not whether it was withheld from the deposit. An ACH per-settlement fee reported before its day's deposit gains this link once that deposit is reported.

Example: "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN"

settledTransaction SettledTransactionReference

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}.

Child attributes

transactionId string

The transaction ID (trx_) of the settled transaction, when that line is matched to a transaction. Absent when matchStatus is Unmatched.

Example: "trx_01JZ5EXH9GVK3M7T2QSBWD48RC"

gatewayTransactionId string required

The gateway's own transaction ID of the settled transaction. Always present.

Example: "1620000000770632947"

matchStatus string required

The match status of the settled transaction - the same matchStatus reported on that settled transaction.

Unmatched: The settled transaction has no identified transaction; transactionId is absent.

Matched: Automatically matched to a transaction.

ManuallyMatched: Matched to a transaction by manual reconciliation.

Allowed: Unmatched, Matched, ManuallyMatched

Example: "Matched"

feeBreakdown SettlementFeeBreakdown

Optional breakdown of the components of a fee charge. Only the components that apply to a given fee are present. Components are signed integers in minor units; positive values are charges and negative values are credits.

Child attributes

discountFee integer

Processing/discount fee component, smallest denomination.

originationFee integer

ACH origination fee, smallest denomination.

returnFee integer

ACH return fee - charged when a transaction is returned/reversed post-settlement. Smallest denomination.

interchangeFee integer

Card-network interchange fee, in minor units.

otherFee integer

Provider-specific catch-all for fee components not otherwise modeled.

July charges for June - a named fee, the statement's interchange and passthrough, and an unclassified fee

{
  "totalCount": 3,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5G4K8WQT2XB7RD9NVMC3EH",
      "source": "StatementOnly",
      "category": "AuthorizationFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 2995,
      "chargeDate": "2026-07-01",
      "periodStart": "2026-06-01",
      "periodEnd": "2026-06-30",
      "description": "AUTHORIZATION FEES",
      "assessmentDate": "2026-07-01",
      "componentFeeCount": 0,
      "feeUnitCount": 100
    },
    {
      "id": "mfc_01JZ5G4K8WYN6PSA3KTE5D2QVX",
      "source": "StatementOnly",
      "category": "InterchangeAndPassthrough",
      "status": "Billed",
      "currency": "USD",
      "amount": 3299,
      "chargeDate": "2026-07-01",
      "periodStart": "2026-06-01",
      "periodEnd": "2026-06-30",
      "description": "Interchange and Passthrough fees",
      "assessmentDate": "2026-07-01",
      "componentFeeCount": 0
    },
    {
      "id": "mfc_01JZ5G4K8XCD4RQY7KME2W9SVB",
      "source": "StatementOnly",
      "category": "Other",
      "status": "Billed",
      "currency": "USD",
      "amount": 400,
      "chargeDate": "2026-07-01",
      "periodStart": "2026-06-01",
      "periodEnd": "2026-06-30",
      "description": "NEW PROVIDER FEE WORDING",
      "assessmentDate": "2026-07-01",
      "componentFeeCount": 0,
      "feeUnitCount": 1
    }
  ]
}

An ACH fee assessed against one settled transaction

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5G4K8WZP7QDB4MTF6E3RWY",
      "source": "SettlementLinked",
      "category": "TransactionFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 127,
      "chargeDate": "2026-07-01",
      "description": "Per-transaction settlement fee",
      "settlementId": "stl_01JZ5F1P7A2C9E4G6H8K0M2N4Q",
      "settledTransaction": {
        "transactionId": "trx_01JZ5EXH9GVK3M7T2QSBWD48RC",
        "gatewayTransactionId": "1620000000770632947",
        "matchStatus": "Matched"
      },
      "feeBreakdown": {
        "originationFee": 127
      },
      "assessmentDate": "2026-07-01",
      "componentFeeCount": 0
    }
  ]
}

Card Net fees already deducted from the deposit

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5G7S4KT8QD2VX3MN6P9WBC",
      "source": "SettlementLinked",
      "category": "DailyInterchangeFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 75,
      "chargeDate": "2026-07-01",
      "description": "Daily interchange fee",
      "settlementId": "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN",
      "feeBreakdown": {
        "interchangeFee": 75
      },
      "assessmentDate": "2026-07-01",
      "componentFeeCount": 0
    },
    {
      "id": "mfc_01JZ5G8T6RP4DX9KN7V2MC3WQH",
      "source": "SettlementLinked",
      "category": "DailyDiscountFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 150,
      "chargeDate": "2026-07-01",
      "description": "Daily discount fee",
      "settlementId": "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN",
      "feeBreakdown": {
        "discountFee": 150
      },
      "assessmentDate": "2026-07-01",
      "componentFeeCount": 0
    }
  ]
}

Card Gross daily fees billed through monthly rollups

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH",
      "source": "StatementOnly",
      "category": "DailyInterchangeFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 75,
      "chargeDate": "2026-08-01",
      "description": "Daily interchange fee",
      "periodStart": "2026-07-01",
      "periodEnd": "2026-07-31",
      "assessmentDate": "2026-08-01",
      "componentFeeCount": 1
    },
    {
      "id": "mfc_01JZ5GBW2KT9RM4DQ6V8PC3NXH",
      "source": "StatementOnly",
      "category": "DailyDiscountFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 150,
      "chargeDate": "2026-08-01",
      "description": "Daily discount fee",
      "periodStart": "2026-07-01",
      "periodEnd": "2026-07-31",
      "assessmentDate": "2026-08-01",
      "componentFeeCount": 1
    }
  ]
}

A July component selected by assessment date

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5GCX4YH8KV6M2RT9NW3PQB",
      "source": "SettlementLinked",
      "category": "DailyInterchangeFee",
      "status": "Informational",
      "currency": "USD",
      "amount": 75,
      "assessmentDate": "2026-07-01",
      "chargeDate": "2026-08-01",
      "parentFeeId": "mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH",
      "componentFeeCount": 0,
      "description": "Daily interchange fee",
      "settlementId": "stl_01JZ5F2R8K6M9WC4Q7X3TDHPBV",
      "feeBreakdown": {
        "interchangeFee": 75
      }
    }
  ]
}

The same monthly rollup before its statement is processed

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH",
      "source": "StatementOnly",
      "category": "DailyInterchangeFee",
      "status": "Pending",
      "currency": "USD",
      "amount": 75,
      "chargeDate": "2026-08-01",
      "description": "Daily interchange fee",
      "periodStart": "2026-07-01",
      "periodEnd": "2026-07-31",
      "assessmentDate": "2026-08-01",
      "componentFeeCount": 1
    }
  ]
}

The statement's discount for flat-rate pricing

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5GDY6QK3RT8NW2MV9PX4HC",
      "source": "StatementOnly",
      "category": "DiscountFee",
      "status": "Billed",
      "currency": "USD",
      "amount": 3299,
      "assessmentDate": "2026-07-01",
      "chargeDate": "2026-07-01",
      "periodStart": "2026-06-01",
      "periodEnd": "2026-06-30",
      "componentFeeCount": 0,
      "description": "Discount fee"
    }
  ]
}

400

Invalid request, including missing date parameters or an invalid includeInformational boolean.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Allowed: 0, 1000, 1001, 2000, 2010, 2011, 2012, 2013, 2014, 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

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

403

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

reportingAccessDisabled

{
  "code": 1001,
  "status": "Rejected",
  "message": "Settlement reporting API access is not enabled for this merchant.",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-09-16T12:00:00Z",
  "errorDetails": []
}

List Fee Charge Components

GET/fee-charges/{feeChargeId}/components

Returns the informational daily fees that a monthly rollup sums, with their settlement and settled-transaction references when available. Uses the same paginated fee-charge response as the listing. Neither date parameters nor includeInformational are required.

A fee you own with no components returns 200 with an empty page. A malformed feeChargeId returns 400. An unknown ID or another merchant's ID returns 404. Only the authenticated merchant's records are returned.

Read all pages to check the parent rollup's amount and componentFeeCount. Components remain Informational after the parent is Billed; do not add them to billed totals.

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

Parameters

Name	In	Type	Description
`feeChargeId` required	path	string	The monthly rollup fee charge ID. A fee you own with no components returns an empty page.
`merchantIds`	query	string	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.
`filters`	query	string	Comma-separated filter expressions within this rollup. Fields: category, source, amount, chargeDate, assessmentDate, parentFeeId. Status is not a filter field.
`sorts`	query	string	Comma-separated field names; prefix with - for descending order. Fields: category, source, amount, chargeDate, assessmentDate. parentFeeId and status are not sort fields. Default order: assessmentDate ascending, then fee ID. A supplied sort replaces the default order.
`page`	query	integer	Page number to retrieve (starts at 1). For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.
`pageSize`	query	integer	Number of records per page. For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.

Responses

200

The component fees, or an empty page for a fee with no components.

application/json · FeeChargesListResponse

totalCount integer required

Total number of fee charges that match the filter criteria

Example: 2

page integer required

The current page number (starts at 1)

Example: 1

pageSize integer required

Number of items per page

Example: 10

totalPages integer required

Total number of pages available

Example: 1

hasNextPage boolean required

True if there are more pages of results available

Example: false

hasPreviousPage boolean required

True if there are previous pages of results available

Example: false

items array of FeeCharge required

Array of fee charges for the current page

Child attributes

id string required

The fee charge ID, prefixed with mfc_.

Example: "mfc_01JZ5G4K8WQT2XB7RD9NVMC3EH"

category string required

General fee categories:

MonthlyService - fees for maintaining the merchant account and related payment services, such as statements, reporting, and gateway services.
PciCompliance - fees related to Payment Card Industry (PCI) compliance, including compliance services and non-compliance assessments.
OneTimeSetup - one-time fees for setting up a service, such as an account, gateway, or wireless connection.
NetworkAssessment - card-network charges passed through to the merchant, such as registration or network participation fees.
Equipment - fees for payment terminals and related hardware, including charges for equipment that was not returned.
TransactionFee - per-transaction processing costs, including fees assessed on individual settled transactions and per-item or authorization charges billed on a monthly card statement.
Other - fees with no more specific classification. Read description for the reported fee wording.

Transaction and settlement fees (daily fees have source: SettlementLinked; under monthly billing their rollups have source: StatementOnly):

DailyDiscountFee - the daily discount fee assessed against a card settlement.
DailyInterchangeFee - the daily interchange fee assessed against a card settlement.
TransactionFee - a per-transaction settlement fee, e.g. an ACH transaction's processing fee.
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. The fee of an ACH entry the bank returned is reported as ReturnFee when the processor reports it as a return fee, otherwise as TransactionFee.
ChargebackFee - charged when the payer's bank returns an ACH payment after the funds reached the merchant. description is Chargeback fee. Its settledTransaction is the Chargeback line on the deposit of the day the return settled, not the sale's line. Under monthly billing it rolls up under its own ChargebackFee parent.
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.

Fees billed on a monthly statement or invoice (source is StatementOnly). Representative examples by general category:

MonthlyService: GatewayService, StatementFee, WebReportsAlerts.
PciCompliance: PciFee, NonComplianceAssessment, SaqScanIncomplete.
OneTimeSetup: ApplicationFee, GatewaySetup, WirelessActivation.
NetworkAssessment: VisaRegistrationFee, McRegistrationFee, PinBasedDebitNetworkFee.
Equipment: UnreturnedEquipment.
TransactionFee: per-item or authorization charges classified as per-transaction. A named charge uses its specific fee name in category.
Other: an unclassified fee or unrecognized statement wording; read description.

Card processing costs on the statement:

InterchangeAndPassthrough - interchange and the card-network costs the monthly card statement passes through to the merchant, read from the statement lines reported under this category. Typical for cost-plus pricing.
DiscountFee - the month's discount as the card statement's summary prints it. Typical for flat-rate pricing.

Description wording can vary; use category as the identifier. Changes to pricing or wording do not relabel previously reported fees.

Example: "AuthorizationFee"

source string required

Where the fee was reported, independently of its billing schedule.

Use status and chargeDate for billing. Funding type controls whether fees reduce the deposit. Do not deduct a withheld fee from a deposit amount that already includes that deduction.

Allowed: SettlementLinked, StatementOnly

Example: "StatementOnly"

status string required

Billed fees are charged to the merchant and are the only records returned by the default fee listing.

Allowed: Billed, Pending, Informational

Example: "Billed"

currency string required

Allowed: USD, CAD

Example: "USD"

amount integer (int64) required

Example: 2995

assessmentDate string (date) required

The settlement date for a daily fee. For a statement or invoice fee and a rollup, it equals chargeDate. Informational fees are selected by this date when includeInformational=true.

Example: "2026-07-01"

chargeDate string (date) required

Example: "2026-07-01"

periodStart string (date)

Start of the period covered by a statement or invoice fee or monthly rollup. Absent on settlement-linked fees, including informational components.

Example: "2026-06-01"

periodEnd string (date)

End of the period covered by a statement or invoice fee or monthly rollup. Absent on settlement-linked fees, including informational components.

Example: "2026-06-30"

parentFeeId string

The monthly rollup's mfc_ ID on an informational component. Absent on other fees. GET /fee-charges/{feeChargeId}/components lists the rollup's components.

pattern "^mfc_[0-9A-HJKMNP-TV-Z]{26}$"

Example: "mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH"

componentFeeCount integer required

Number of daily component fees in a rollup. Always returned; 0 on other fees. It is not feeUnitCount.

min 0

Example: 10

feeUnitCount integer (int32)

min 1 · max 2147483647

Example: 100

description string

Human-readable fee wording. It can vary; use category to identify the fee type.

Example: "Monthly service fee - June 2026"

settlementId string

Example: "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN"

settledTransaction SettledTransactionReference

Child attributes

transactionId string

The transaction ID (trx_) of the settled transaction, when that line is matched to a transaction. Absent when matchStatus is Unmatched.

Example: "trx_01JZ5EXH9GVK3M7T2QSBWD48RC"

gatewayTransactionId string required

The gateway's own transaction ID of the settled transaction. Always present.

Example: "1620000000770632947"

matchStatus string required

The match status of the settled transaction - the same matchStatus reported on that settled transaction.

Unmatched: The settled transaction has no identified transaction; transactionId is absent.

Matched: Automatically matched to a transaction.

ManuallyMatched: Matched to a transaction by manual reconciliation.

Allowed: Unmatched, Matched, ManuallyMatched

Example: "Matched"

feeBreakdown SettlementFeeBreakdown

Child attributes

discountFee integer

Processing/discount fee component, smallest denomination.

originationFee integer

ACH origination fee, smallest denomination.

returnFee integer

ACH return fee - charged when a transaction is returned/reversed post-settlement. Smallest denomination.

interchangeFee integer

Card-network interchange fee, in minor units.

otherFee integer

Provider-specific catch-all for fee components not otherwise modeled.

Component of the monthly interchange rollup

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "mfc_01JZ5GCX4YH8KV6M2RT9NW3PQB",
      "source": "SettlementLinked",
      "category": "DailyInterchangeFee",
      "status": "Informational",
      "currency": "USD",
      "amount": 75,
      "assessmentDate": "2026-07-01",
      "chargeDate": "2026-08-01",
      "parentFeeId": "mfc_01JZ5G9V8MP2TD6QW4N7XC3RKH",
      "componentFeeCount": 0,
      "description": "Daily interchange fee",
      "settlementId": "stl_01JZ5F2R8K6M9WC4Q7X3TDHPBV",
      "feeBreakdown": {
        "interchangeFee": 75
      }
    }
  ]
}

An owned fee with no components

{
  "totalCount": 0,
  "page": 1,
  "pageSize": 10,
  "totalPages": 0,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": []
}

400

Invalid request, including a malformed feeChargeId.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

403

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

reportingAccessDisabled

{
  "code": 1001,
  "status": "Rejected",
  "message": "Settlement reporting API access is not enabled for this merchant.",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-09-16T12:00:00Z",
  "errorDetails": []
}

404

The fee charge does not exist or does not belong to the merchant.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
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.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
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.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
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.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."