> For the complete documentation index, see [llms.txt](https://docs.sensepass.com/sensepay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sensepass.com/sensepay/transaction-api/payment-flows/surcharge.md). # Surcharge ### Surcharging integration guide SensePass applies surcharges during authorization and capture. Always send the base amount, before surcharge. Do not pre-add or reverse-engineer the fee. A location surcharge row replaces the merchant row. It does not merge with it. If the location has no saved surcharge config, the merchant config is used. ### Prerequisites A fee is charged only when every requirement below is met. | # | Requirement | Where it is set | | - | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | 1 | This transaction is not waived. | Init or pay: `waiveSurcharge` omitted or `false`. A pay value overrides init. | | 2 | Surcharging is enabled for the effective config. | Partner Dashboard → Surcharge | | 3 | A rule matches the gateway and the payment method. | Partner Dashboard → Surcharge → Surcharge Rules | | 4 | The card is credit, or the method is a non-card target (ACH, Samsung Pay, Google Pay card-on-file). Debit and prepaid are never surcharged. | Card funding comes from the BIN or the wallet, never from a credit/debit button. | | 5 | For card payments, a known US state is available and that state permits surcharging. | In-store: store state on the surcharge config. E-commerce: customer ZIP or state. See **Customer location**. | When an exact target (for example Visa Credit) and an **All sources** row both match the same gateway, the exact target wins. Among rows with the same target, the first row wins. A rule with no gateway never matches. A gateway value of “any processor” matches every gateway. **All sources** is an empty target on that gateway. It is not a cross-gateway rule. **Apply to → Transactions ≥** is inclusive: the base must be greater than or equal to the threshold. Rules can be a percentage or a fixed amount. For cards, that value is a ceiling. SensePass charges the lowest amount still allowed by state law, card network, merchant processing cost, and equal treatment. Fixed fees are capped the same way: the fee cannot exceed `base × max allowed percent`. A saved debit or prepaid rule does not charge a fee. Rows whose target is unrecognized funding are ignored. ### When there is no fee The sale can still be approved for the base amount. **No `surcharge` object.** SensePass did not evaluate a fee: * Surcharging is off, or there is no config. * No rule matches this gateway and payment method. * The card brand or funding was never resolved (unknown BIN on a card that is not a wallet device token). **`surcharge` is present and `amount` is `0`.** A decision was stored. Read `flags` and `decision.decidingRule.source`. | Situation | `flags` | `decision.decidingRule.source` | | ------------------------------------------------------------------------------- | ----------------------------- | ------------------------------ | | `waiveSurcharge` is `true` | `SURCHARGE_WAIVED_BY_REQUEST` | `transaction_waiver` | | Debit or prepaid | | `funding_block` | | Apple Pay or Google Pay device token and the underlying card funding is unknown | `FUNDING_UNRESOLVED` | | | E-commerce card payment and no US state could be resolved | `REQUIRES_CUSTOMER_LOCATION` | | | State, network, cost, equal treatment, or registration blocked the fee | `SURCHARGE_NOT_PERMITTED` | `regulation_block` | A hosted checkout pill can show a range before the card is identified. That range is the disclosure maximum. The charged amount is resolved at pay time and can be lower, including `$0`. `methodType: "Tokenize"` does not apply a surcharge. The fee is resolved when that token is charged. ### Customer location Card surcharges need a US state that exists in the SensePass state table. ACH, Samsung Pay, and Google Pay card-on-file (`PAN_ONLY`) do not need a ZIP or state, and state law does not cap those fees. **In-store.** The store state on the surcharge config is used. Billing ZIP does not override it. If that code is not in the state table, the in-store state is not applied and resolution continues as e-commerce. `DC` is selectable in Partners and is not in the state table. **E-commerce.** The first source that resolves to a known US state is used: 1. `surchargePostalCode` on the pay request (ZIP lookup) 2. `surchargeCustomerStateCode` on the pay request 3. Apple Pay wallet address stored for this payment 4. `billingInformation.postal_code`, then `billingInformation.region` 5. ZIP or state already saved on this transaction 6. The parent authorization, for a capture that does not collect a new ZIP 7. Billing address stored on the transaction 8. ZIP or state stored on the card token A ZIP that is not a US ZIP, or a state that is not in the table, does not count. Card surcharge is then `$0` with `REQUIRES_CUSTOMER_LOCATION`. ```json { "surchargePostalCode": "43215", "surchargeCustomerStateCode": "OH" } ``` Send a ZIP when you have one. State is the fallback when ZIP lookup is unavailable. ### Regional support Card surcharging applies to US states and Puerto Rico in the SensePass state table. A card payment whose location does not resolve to one of those codes is not surcharged. The table below is the seeded rule set. The database is authoritative and can change without a doc update. | Status | State codes | Effect on card surcharges | | ------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Prohibited | `CA`, `CT`, `ME`, `MA`, `PR` | Fee is `$0`. | | Capped (fixed %) | `CO` (2%), `MT` (3%), `MD` (4%), `MN` (5%) | Rate is reduced to the state maximum. | | Capped (cost-based) | `GA`, `NE`, `NV`, `NJ`, `NY`, `SD` | Rate is reduced to the merchant’s processing cost. In `SD`, the cap is the lower of 4% and cost. If cost is not configured, the fee is `$0`. | | Disclosure-only | `TX`, `VA`, `RI`, `WY` | No numeric state cap. Network caps still apply. | | Permitted | All other seeded US states | Configured rate applies, subject to network caps and merchant cost. | These caps run for a card payment when a merchant regulation profile is active or a customer state was resolved. If neither is true, the configured card fee is charged with no state or network ceiling. ACH, Samsung Pay, and Google Pay card-on-file skip this table. ### Funding type and wallets * Credit cards can be surcharged, subject to the caps above. * Debit and prepaid are never surcharged, including debit that runs as credit. The result is `surcharge.amount = 0` and `decision.decidingRule.source = "funding_block"`. * Apple Pay uses the underlying card. Target order is brand and funding (for example `surcharge:visa_credit`), then `surcharge:applepay_credit` or `surcharge:applepay_debit`, then **All sources**. An unresolved Apple Pay device token is `$0` with `FUNDING_UNRESOLVED`. * After the caps, Apple Pay is reduced again so the sale total, surcharge, and surcharge tax fit inside the amount the wallet sheet approved (`applePayAuthorizedTotal`). That reduction is `decision.decidingRule.source = "apple_pay_auth_clamp"`. * Google Pay device tokens (`CRYPTOGRAM_3DS`) with unresolved funding are `$0` with `FUNDING_UNRESOLVED`. Google Pay card-on-file (`PAN_ONLY`) uses the `surcharge:google_pay` rule only. * Samsung Pay uses `surcharge:samsung_pay`. ACH uses `surcharge:ach`. ### Network caps, cost, and registration For card payments, the ceiling is the lowest applicable cap. | Network | Maximum surcharge | | ---------------- | ----------------------------------------------------------------------------------------- | | Visa | Lower of merchant processing cost or 3%. If cost is missing, the 3% cap is still applied. | | Mastercard | Lower of merchant processing cost or 4%. If cost is missing, the 4% cap is still applied. | | American Express | Merchant processing cost. If cost is missing, the fee is `$0`. | | Discover | Merchant processing cost. If cost is missing, the fee is `$0`. | Equal treatment then applies the lowest fixed network cap across brands. That ceiling is Visa’s 3%, so American Express and Discover can be reduced to 3% even when their own rule is cost of acceptance. If the merchant profile requires network registration and registration is incomplete, the card fee is `$0` (`SURCHARGE_NOT_PERMITTED`). If regulation throws, the card fee fails closed to `$0`. `surcharge.percentage` is the rate actually charged after these caps, not the rate configured in Partners. The configured rate is `surcharge.decision.merchantRule.configuredValue`. ### Taxation of surcharge SensePass does not recompute platform tax. `originalTaxAmount` stays as sent. SensePass adds the surcharge and, when the state says so, tax on that surcharge. The state used for tax is the same state used for the fee: store state in-store, customer state for e-commerce. ``` effectiveTaxRate = originalTaxAmount / originalAmountBeforeTax surchargeCalculationBase = PRE_TAX ? originalAmountBeforeTax : originalTotalAfterTax surchargeAmount = already decided fee (percentage, fixed, or after caps) surchargeTaxAmount = (surchargeTaxTreatment == TAXABLE) ? surchargeAmount * effectiveTaxRate : 0 finalAmount = originalTotalAfterTax + surchargeAmount + surchargeTaxAmount ``` Seeded behavior: * `surchargeBase` is `PRE_TAX` for every seeded state. * `surchargeTaxTreatment` is `NON_TAXABLE` in Colorado and `TAXABLE` in every other seeded state. * A Partners “taxable” flag is used only when the state row has no treatment. * A basket with `originalTaxAmount = 0` never adds surcharge tax. * `taxableAmount` and `nonTaxableAmount` are stored and are not used in the formula. If the tax fields are missing or inconsistent, SensePass does not invent tax. The sale `amount` is the base and `originalTaxAmount` is treated as `0`. Inconsistent means any of: * `originalTotalAfterTax` disagrees with `amount` * `originalAmountBeforeTax + originalTaxAmount` disagrees with `originalTotalAfterTax` * only some of the three money fields are present * negative pre-tax or tax amounts * tax greater than the after-tax total * tax with a `$0` pre-tax amount * non-numeric values On a partial capture, the capture amount is the stage base. Capturing the original after-tax total, or the already surcharged authorized total, reuses the original tax split. If tax inputs are present, a percentage uses `originalAmountBeforeTax` (pre-tax). A branch service fee is included in that base only when it is already inside the tax fields you send. If you omit tax fields, the percentage applies to `transaction.amount`, which includes a service fee that was added at init. ### Integration flows #### Send the base amount Init `amount` and the tax fields use the same unit: cents when `isCent` is `true`, major units when `isCent` is omitted or `false`. `10800` with `isCent: true` is `$108.00`. `POST /transactions/pay` `amount` is cents only. If `isCent` is `true` and the tax fields are already in dollars and already match `amount` (for example `100` / `8` / `108` next to `amount: 10800`), SensePass keeps the dollars. Send cents anyway. #### Payment (sale) `POST /transactions/init` with `methodType: "Payment"`. The customer completes hosted checkout or the SDK. SensePass resolves and applies the fee. ```json { "timeOut": 600, "amount": 10800, "isCent": true, "currency": "USD", "deviceId": "your-device-id", "callbackURL": "https://example.com/callback", "methodType": "Payment", "originalAmountBeforeTax": 10000, "originalTaxAmount": 800, "originalTotalAfterTax": 10800, "taxableAmount": 10000, "nonTaxableAmount": 0 } ``` That request is a `$100` pre-tax sale, `$8` tax, `$108` before surcharge. | Field | Type | Required | Description | | ---------------------------- | ----------------- | ----------- | ---------------------------------------------------------------------------- | | `originalAmountBeforeTax` | number \| string | Recommended | Pre-tax sale amount. Same unit as init `amount`. | | `originalTaxAmount` | number \| string | Recommended | Platform tax. Same unit as init `amount`. | | `originalTotalAfterTax` | number \| string | Recommended | Sale total after platform tax, before surcharge. Same unit as init `amount`. | | `taxableAmount` | number \| string | Optional | Stored only. Same unit as init `amount`. | | `nonTaxableAmount` | number \| string | Optional | Stored only. Same unit as init `amount`. | | `waiveSurcharge` | boolean \| string | Optional | `true` charges `$0` surcharge and `$0` surcharge tax. Default `false`. | | `surchargeWaiverReason` | string | Optional | Audit text. Ignored unless `waiveSurcharge` is `true`. | | `surchargePostalCode` | string | Optional | E-commerce ZIP for this payment. | | `surchargeCustomerStateCode` | string | Optional | E-commerce state when ZIP is not sent. | The same fields are accepted on pay and capture. On pay, `waiveSurcharge` replaces the value stored at init. `surchargeWaiverReason` does not waive by itself. After init, the stored copies are `metadata.surchargeTaxInputs` and `metadata.surchargeWaiver`. To waive one transaction: ```json { "waiveSurcharge": true, "surchargeWaiverReason": "government_exempt" } ``` #### Authorize and capture Send the base amount at authorization and at each capture. `POST /transactions/init` with `methodType: "Authorize"`: ```json { "timeOut": 600, "amount": 10800, "isCent": true, "currency": "USD", "deviceId": "your-device-id", "callbackURL": "https://example.com/callback", "methodType": "Authorize", "originalAmountBeforeTax": 10000, "originalTaxAmount": 800, "originalTotalAfterTax": 10800 } ``` Read the authorization token from `paymentDetails.token` on the callback. `POST /transactions/pay`: ```json { "deviceId": "your-device-id", "amount": 10800, "token": "your-payment-token" } ``` `amount` here is cents. One full capture or several smaller captures are allowed. The sum of captures cannot exceed the authorized amount. A capture equal to the original after-tax total reuses the original tax split. Any other capture amount is a new base, and the fee and surcharge tax are calculated on that amount. Each capture can add its own surcharge. `lifecycleStage` is `SALE`, `AUTHORIZE`, or `CAPTURE`. Authorize responses include `authorizedAmount`. Capture responses include `capturedAmount`. For an Authorize.net token, send `tokenSource` and `tokenData` instead of `token`. ```json { "deviceId": "your-device-id", "amount": 10800, "tokenSource": "Authorize.net", "tokenData": { "profile_id": "12121212", "payment_id": "32323232", "auth_code": "ABC123" } } ``` Related endpoints: * Re-authorize: `POST /transactions/authorize` * Void: `POST /transactions/void` * Close authorization: `POST /transactions/{transactionNumber}/closeAuth` (Sola only) An uncaptured authorization is released after timeout or void. A declined or failed payment restores `amount` to the pre-surcharge total and removes a provisional fee. A `$0` decision is kept so a retry can still show why the fee was suppressed. #### Tokenization Create a token with `methodType: "Tokenize"` or `"Capture+Tokenize"`. The callback returns `paymentDetails.token`. Tokenize itself does not add a surcharge. For PCI environments, use `POST /transactions/tokenize` with `apiKey` and `creditCardDetails[]`. Charge the token with `POST /transactions/pay`. The fee is resolved at charge time from the stored card. Credit tokens are surcharged when the gates pass. Unknown funding is not surcharged. `POST /transactions/token-validation` checks that the token can still be charged and returns AVS and CVV. It does not calculate a surcharge. ### Surcharge in responses The stored metadata key is `paymentSurcharge`. API payloads expose it as `surcharge`. Prefer `surcharge` when both exist. Amounts on `surcharge` are major currency units. | Channel | Notes | | --------------------------- | -------------------------------------------------------------- | | Get transaction | Top-level `surcharge` when a decision was stored. | | Successful payment response | Included when a decision was stored. | | Merchant callback | Included when `callbackURL` was set and a decision was stored. | #### `surcharge` object | Field | Type | Description | | --------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | `amount` | number | Surcharge in major units. `0` when a decision suppressed the fee. | | `baseBeforeSurcharge` | number | Sale total before surcharge. This is `originalTotalAfterTax` when tax inputs were accepted. | | `totalAmount` | number | `baseBeforeSurcharge + amount + surchargeTaxAmount`. | | `refundable` | boolean | `true` when refund policy is full or unset. `false` when policy is partial. | | `displayName` | string | Customer label. Default `Processing Fee`. | | `detailLineShort` | string | Percentage: `3% - Processing Fee`. Fixed: `1.5$ fixed - Processing Fee`. | | `summaryDescription` | string | Percentage: `Processing Fee (3%) - Applied to Visa Credit`. | | `surchargeTarget` | string | Matched target, such as `surcharge:visa_credit`. | | `type` | `percentage` \| `fixed` | Rule type. | | `percentage` | number | Effective percent charged after caps. | | `fixedAmount` | number | Configured fixed fee, in major units. | | `surchargeTaxAmount` | number | Tax on the surcharge. `0` when the state is non-taxable or platform tax is `0`. | | `originalAmountBeforeTax` | number | Stored pre-tax amount, major units. | | `originalTaxAmount` | number | Stored platform tax, major units. | | `originalTotalAfterTax` | number | Stored sale total after platform tax, before surcharge. | | `surchargeCalculationBase` | number | Base the fee was calculated on. | | `effectiveTaxRate` | number | `originalTaxAmount / originalAmountBeforeTax`. | | `revisedTotalTaxAmount` | number | `originalTaxAmount + surchargeTaxAmount`. | | `surchargeBase` | string | `PRE_TAX` or `TAX_INCLUSIVE`. | | `surchargeTaxTreatment` | string | `TAXABLE` or `NON_TAXABLE`. | | `surchargeTaxRateSource` | string | `EFFECTIVE_RATE`. | | `formulaApplied` | string | Formula trace. | | `flags` | string\[] | `SURCHARGE_WAIVED_BY_REQUEST`, `FUNDING_UNRESOLVED`, `REQUIRES_CUSTOMER_LOCATION`, `SURCHARGE_NOT_PERMITTED`. | | `lifecycleStage` | string | `SALE`, `AUTHORIZE`, or `CAPTURE`. | | `authorizedAmount` | number | Present on authorize. Charged total including surcharge. | | `capturedAmount` | number | Present on capture. Charged total including surcharge. | | `merchantState` | string \| null | In-store state from config. | | `customerState` | string \| null | State used for e-commerce rules. | | `walletType` | string | `APPLE_PAY`, `GOOGLE_PAY`, or `NONE`. | | `tokenType` | string | `FPAN`, `DPAN`, or `NONE`. | | `fundingType` | string \| null | `credit`, `debit`, `prepaid`, or `unknown`. | | `underlyingFundingResolved` | boolean | `false` when a wallet device token did not yield card funding. | | `ruleVersion` | string | Config version label. Default `location-config`. | | `waiveSurcharge` | boolean | `true` when this transaction was waived. | | `surchargeWaiverReason` | string | Audit reason, when sent with an active waiver. | `decision` explains which layer set the fee: | Field | Description | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `decision.configSource` | `branch` or `merchant`. | | `decision.merchantRule.configuredValue` | Percent or fixed amount configured in Partners, before caps. | | `decision.merchantRule.surchargeTarget` | Rule target. | | `decision.merchantRule.applyToMode` | `all` or `gt`. | | `decision.merchantRule.applyToThreshold` | Minimum base when `applyToMode` is `gt`. | | `decision.regulation.clamped` | `true` when regulation lowered a fee that is still above `0`. | | `decision.regulation.maxAllowedPercent` | Regulatory ceiling. | | `decision.regulation.summary` | One-line reason. | | `decision.decidingRule.source` | `merchant_rule`, `regulation_clamp`, `regulation_block`, `funding_block`, `apple_pay_auth_clamp`, or `transaction_waiver`. | ```json { "surcharge": { "amount": 3, "baseBeforeSurcharge": 108, "totalAmount": 111.24, "refundable": false, "displayName": "Processing Fee", "detailLineShort": "3% - Processing Fee", "summaryDescription": "Processing Fee (3%) - Applied to Visa Credit", "surchargeTarget": "surcharge:visa_credit", "type": "percentage", "percentage": 3, "surchargeTaxAmount": 0.24, "originalAmountBeforeTax": 100, "originalTaxAmount": 8, "originalTotalAfterTax": 108, "surchargeCalculationBase": 100, "effectiveTaxRate": 0.08, "revisedTotalTaxAmount": 8.24, "surchargeBase": "PRE_TAX", "surchargeTaxTreatment": "TAXABLE", "surchargeTaxRateSource": "EFFECTIVE_RATE", "lifecycleStage": "SALE", "customerState": "OH", "fundingType": "credit", "decision": { "configSource": "merchant", "merchantRule": { "surchargeTarget": "surcharge:visa_credit", "type": "percentage", "configuredValue": 3, "applyToMode": "all" }, "decidingRule": { "source": "merchant_rule" } } } } ``` This sample is a 3% credit-card fee on the `$100` pre-tax base, plus 8% tax on that `$3` fee (`$0.24`), in a taxable state. Colorado would return `surchargeTaxAmount: 0`, `surchargeTaxTreatment: "NON_TAXABLE"`, and `totalAmount: 111`. ### Refunds `surcharge.refundable` mirrors the refund policy. Unset policy is full (`refundable: true`). **Full.** SensePass does not split the refund into sale, surcharge, and surcharge tax. You can refund any amount up to the captured balance, which includes the surcharge and surcharge tax. **Partial** (`refundable: false`). The customer refund cannot exceed the pre-surcharge sale total, minus refunds that already succeeded. That cap is `originalTotalAfterTax` when it was stored, otherwise `baseBeforeSurcharge`. The surcharge and the surcharge tax stay with the merchant. A request above the cap is reduced to the cap. The dashboard refund dialog shows the same limit. ### Troubleshooting 1. If `surcharge` is missing, surcharging is off, no rule matched, or card funding was never resolved. 2. If `surcharge.amount` is `0`, read `flags` and `decision.decidingRule.source` in the table above. 3. Confirm `waiveSurcharge` is not `true` on pay. Pay overrides init. 4. Confirm the card BIN is credit. Debit and prepaid store a `$0` decision. 5. For cards, confirm a known US state was resolved. A missing ZIP on an e-commerce credit payment is `REQUIRES_CUSTOMER_LOCATION`. 6. Compare `percentage` with `decision.merchantRule.configuredValue`. A lower `percentage` means a cap was applied. `decision.regulation.summary` names the cap. 7. American Express, Discover, and cost-cap states are `$0` when merchant processing cost is not configured. 8. For Apple Pay, compare the charged total with the wallet sheet total. 9. For surcharge tax, confirm `originalAmountBeforeTax`, `originalTaxAmount`, and `originalTotalAfterTax` were sent in the same unit as `amount`, and that they add up. ### Sandbox testing 1. Use a sandbox card whose BIN resolves to credit. 2. Use an Ohio ZIP (`43215`) or `surchargeCustomerStateCode: "OH"` for e-commerce, or set the in-store state to `OH`. 3. Add a matching percentage rule, such as Visa Credit at 3%. 4. Init with `isCent: true`, `amount: 10800`, `originalAmountBeforeTax: 10000`, `originalTaxAmount: 800`, `originalTotalAfterTax: 10800`. 5. Complete payment. Expect `surcharge.amount` of `3`, `surchargeTaxAmount` of `0.24`, and `totalAmount` of `111.24`. 6. Repeat with Colorado. Expect `surchargeTaxAmount` of `0` and `surchargeTaxTreatment` of `NON_TAXABLE`. 7. Repeat with `waiveSurcharge: true`. Expect `amount` of `0` and `flags` containing `SURCHARGE_WAIVED_BY_REQUEST`. 8. Repeat with a debit BIN. Expect `amount` of `0` and `decision.decidingRule.source` of `funding_block`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sensepass.com/sensepay/transaction-api/payment-flows/surcharge.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.