> 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 automatically within state and card-network limits. Always send the base amount, before surcharge. SensePass adds the correct surcharge during authorization and capture. #### Prerequisites Surcharge is configured per merchant. A location can override the merchant configuration. A surcharge applies only when every requirement below is met. | # | Requirement | Where it is set | | - | -------------------------------------------------------------------------------------- | ------------------------------------------------------- | | 1 | The transaction's surcharge is not waived. | Init or pay: `waiveSurcharge` is omitted or `false` | | 2 | Surcharging is enabled for the location. | Partner Dashboard -> Location -> Surcharge | | 3 | A rule matches the payment method. Use an `All sources` rule or a brand-specific rule. | Partner Dashboard -> Surcharge -> Surcharge Rules | | 4 | The card is a credit card. Debit and prepaid cards are never surcharged. | Determined from the card BIN | | 5 | The applicable state permits surcharging. | Billing ZIP for e-commerce; location state for in-store | When `All sources` and brand-specific rules both match, the most specific rule applies. Rules can use a percentage or fixed amount. A percentage is a ceiling request. SensePass applies the lowest permitted state or network rate. #### When surcharge is $0 SensePass evaluates four gates. If any gate fails, surcharge is `$0`. The transaction can still be approved for its base amount. | Gate | Question | Surcharge is $0 when | | ---- | ---------------------------------------------- | --------------------------------------------------------------------------------------- | | G0 | Was the surcharge waived for this transaction? | `waiveSurcharge` is `true` on init or pay. | | G1 | Is surcharging enabled for this location? | The location toggle is off. | | G2 | Is the card a credit card? | The card is debit, prepaid, or the BIN cannot be resolved. | | G3 | Is there a matching rule? | Neither `All sources` nor a brand-specific rule matches. | | G4 | Does the applicable state permit surcharging? | E-commerce billing ZIP/state or in-store location state resolves to a prohibited state. | #### Regional support Surcharging currently supports US transactions only. No surcharge applies to non-US billing regions. SensePass maintains the active state rules. The backend rule set is authoritative. | Status | State codes | Effect | | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- | | Prohibited | `CA`, `CT`, `ME`, `MA`, `PR` | No surcharge applies. | | Capped (fixed %) | `CO` (2%), `MT` (3%), `MD` (4%), `MN` (5%) | The rate is reduced to the state maximum. | | Capped (cost-based) | `GA`, `NE`, `NV`, `NJ`, `NY`, `SD` | The rate is reduced to processing cost. In `SD`, it is the lower of 4% or cost. | | Disclosure-only | `TX`, `VA`, `RI`, `WY` | No numeric state cap. Network caps still apply. | | Permitted | All other US states | Your configured rate applies, subject to network caps. | #### Funding type and wallets * Credit cards can be surcharged, subject to state and network caps. * Debit and prepaid cards are never surcharged. This applies when debit runs as credit. * Digital wallets inherit the underlying card's funding type. * An unresolved BIN fails closed. No surcharge applies. #### Network caps SensePass always applies card-network caps. | Network | Maximum surcharge | | ---------------- | --------------------------------------- | | Visa | Lower of merchant processing cost or 3% | | Mastercard | Lower of merchant processing cost or 4% | | American Express | Merchant processing cost | | Discover | Merchant processing cost | #### Taxation of surcharge SensePass does not recompute or modify the platform tax amount. Platform remains authoritative for base tax (`originalTaxAmount`). SensePass only adds surcharge and, when applicable, surcharge-tax. Tax treatment comes from state rules for the applicable state: * In-store: location state * E-commerce: customer state from billing ZIP/state Tax formula: ``` effectiveTaxRate = originalTaxAmount / originalAmountBeforeTax surchargeAmount = surchargeRate * surchargeBase surchargeTaxAmount = (surchargeTaxTreatment == TAXABLE) ? surchargeAmount * effectiveTaxRate : 0 finalAmount = originalTotalAfterTax + surchargeAmount + surchargeTaxAmount ``` Current base behavior: * `surchargeBase` is state-configured (`PRE_TAX` or `TAX_INCLUSIVE`) * Until a state sets another value, base defaults to `PRE_TAX` Tax guardrails: * Exempt baskets (`originalTaxAmount = 0`) never add surcharge tax. * If tax inputs are missing, SensePass does not invent tax. #### Integration flows **Send the base amount** Always send the base amount. Do not pre-add or reverse-engineer the surcharge. **Payment (sale)** Create a transaction with `POST /transactions/init` and `methodType: "Payment"`. The customer completes the hosted-page or SDK payment. SensePass resolves, displays, and applies an eligible surcharge. ```json POST /transactions/init { "timeOut": 600, "amount": 10800, "isCent": true, "currency": "USD", "deviceId": "your-device-id", "callbackURL": "https://example.com/callback", "methodType": "Payment", "originalAmountBeforeTax": 100, "originalTaxAmount": 8, "originalTotalAfterTax": 108, "taxableAmount": 100, "nonTaxableAmount": 0 } ``` Tax and waiver fields accepted on init (and also accepted on pay/capture if needed): | Field | Type | Required | Description | | ------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------ | | `originalAmountBeforeTax` | number \| string | Recommended | Pre-tax sale amount. | | `originalTaxAmount` | number \| string | Recommended | Tax already computed by platform | | `originalTotalAfterTax` | number \| string | Recommended | Sale total after tax, before surcharge. | | `taxableAmount` | number \| string | Optional | Taxable portion of basket (stored for future use). | | `nonTaxableAmount` | number \| string | Optional | Non-taxable portion of basket (stored for future use). | | waiveSurcharge | boolean \| string | Optional | Default `false`. When `true`, surcharge and surcharge-tax are `$0` (G0). | | surchargeWaiverReason | string | Optional | Ignored unless `waiveSurcharge` is `true`. | On successful init, these values may also appear under `metadata.surchargeTaxInputs` and `metadata.surchargeWaiver`. To waive surcharge for one transaction (G0), send: ```json { "waiveSurcharge": true, "surchargeWaiverReason": "government_exempt" } ``` `surchargeWaiverReason` is optional and used for audit only. It does not waive surcharge by itself. `amount` is the base amount in cents. The transaction or callback returns `surcharge` when a fee applies. **Authorize and capture** Send the base amount at authorization and capture. The transaction returns `surcharge` when a fee applies. Create the authorization with `POST /transactions/init` and `methodType: "Authorize"`. ```json POST /transactions/init { "timeOut": 600, "amount": 10800, "isCent": true, "currency": "USD", "deviceId": "your-device-id", "callbackURL": "https://example.com/callback", "methodType": "Authorize", "originalAmountBeforeTax": 100, "originalTaxAmount": 8, "originalTotalAfterTax": 108 } ``` After payment, retrieve the authorization token from `paymentDetails.token` in the callback. Capture with `POST /transactions/pay`. Capture once for the full amount or multiple times for smaller amounts. The combined captures cannot exceed the authorized amount. ```json { "deviceId": "your-device-id", "amount": 10800, "token": "your-payment-token" } ``` 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. **Tokenization** Create a token through the hosted flow using `methodType: "Tokenize"` or `"Capture+Tokenize"`. The callback returns the token at `paymentDetails.token`. For PCI environments, use `POST /transactions/tokenize` with `apiKey` and `creditCardDetails[]`. Charge a token with `POST /transactions/pay`. Surcharge resolves at charge time using stored card metadata. Eligible credit-card tokens surcharge normally. Unresolved funding is not surcharged. Validate a token with `POST /transactions/token-validation`. This verifies current chargeability and returns AVS/CVV results. #### Surcharge in responses SensePass persists surcharge details on the transaction. API payloads expose a read-only `surcharge` object after a successful charge. If no surcharge applies, the `surcharge` object is omitted. This indicates that an eligibility gate resolved the amount to `$0`. **Where the object appears** | Channel | Notes | | --------------------------- | -------------------------------------------------------------------------------- | | Get transaction | Transaction detail and filtered payloads include top-level `surcharge` metadata. | | Successful payment response | Approved payments can include `surcharge`. | | Merchant callback (POST) | Included when `callbackURL` is set on the transaction request. | The stored metadata key is `paymentSurcharge`. Responses normally expose a parsed copy as `surcharge`. Prefer `surcharge` when both exist. **`surcharge` object** Core fields: | Field | Type | Description | | --------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- | | `amount` | number | Surcharge amount in the transaction currency. | | `baseBeforeSurcharge` | number | Amount used to calculate the fee. | | `totalAmount` | number | Total amount after surcharge (and surcharge tax if applicable). | | `refundable` | boolean | `false` retains surcharge/surcharge-tax on refunds. `true` refunds proportionally. | | `displayName` | string | Customer-facing label, such as `Processing fee`. | | `detailLineShort` | string | Short receipt or UI line. | | `summaryDescription` | string | Longer customer-facing description. | | `surchargeTarget` | string (optional) | Internal target, such as `surcharge:visa_credit`. | | `type` | `percentage` \| `fixed` (optional) | Applied rule type. | | `percentage` | number (optional) | Configured percentage rate. | | `fixedAmount` | number (optional) | Configured fixed fee. | Tax and explainability fields: | Field | Type | Description | | -------------------------- | -------------- | -------------------------------------------------------------------------------------- | | `surchargeTaxAmount` | number | Tax amount applied on top of surcharge. | | `originalAmountBeforeTax` | number | Stored pre-tax amount from request/metadata. | | `originalTaxAmount` | number | Stored base tax amount from request/metadata (not recomputed). | | `originalTotalAfterTax` | number | Stored sale total after base tax and before surcharge. | | `surchargeCalculationBase` | number | Base used for surcharge calculation. | | `effectiveTaxRate` | number | Derived as `originalTaxAmount / originalAmountBeforeTax`. | | `revisedTotalTaxAmount` | number | `originalTaxAmount + surchargeTaxAmount`. | | `surchargeBase` | string | `PRE_TAX` or `TAX_INCLUSIVE`. | | `surchargeTaxTreatment` | string | `TAXABLE` or `NON_TAXABLE`. | | `surchargeTaxRateSource` | string | Current source is `EFFECTIVE_RATE`. | | `formulaApplied` | string | Formula trace for auditing/debugging. | | `flags` | string\[] | Decision flags (for example `SURCHARGE_NOT_PERMITTED`, `SURCHARGE_WAIVED_BY_REQUEST`). | | `lifecycleStage` | string | `SALE`, `AUTHORIZE`, or `CAPTURE`. | | `merchantState` | string \| null | Merchant/location state used for in-store rules. | | `customerState` | string \| null | Customer state used for e-commerce rules. | | waiveSurcharge | boolean | `true` when G0 waived the surcharge. | | surchargeWaiverReason | string | Audit reason supplied with the waiver. | ```json { "surcharge": { "amount": 3.0, "baseBeforeSurcharge": 108, "totalAmount": 111.24, "refundable": false, "displayName": "Processing fee", "detailLineShort": "Processing fee 3.0%", "summaryDescription": "A processing fee applies to credit card payments.", "surchargeTarget": "surcharge:visa_credit", "type": "percentage", "percentage": 3.0, "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" } } ``` #### Refunds Refunds include the proportional surcharge by default. A merchant or location can instead retain the surcharge on refunds. `surcharge.refundable` reflects that policy. When `false`, downstream refunds are capped to exclude the surcharge portion (and corresponding surcharge tax). When `true`, surcharge and surcharge-tax are refunded proportionally with the captured amount. #### Troubleshooting Work through the eligibility gates in order: 1. Confirm `waiveSurcharge` is not `true` on init or pay. 2. Confirm surcharging is enabled for the location. 3. Confirm the card BIN resolves to credit funding. 4. Confirm that `All sources` or a brand-specific rule matches. 5. Confirm that the applicable state is permitted (billing ZIP/state for e-commerce, location state for in-store). 6. If all gates pass, confirm whether a state or network cap reduced the rate. 7. If tax fields are missing, confirm init/pay payload includes `originalAmountBeforeTax`, `originalTaxAmount`, and `originalTotalAfterTax`. Check the payment or transaction response. An omitted `surcharge` object confirms a gate resolved the surcharge to `$0`. When present, `surchargeTarget` shows the matched rule. #### Sandbox testing 1. Use a sandbox card whose BIN resolves to credit funding. 2. Use an Ohio ZIP/state for e-commerce, or configure an Ohio location state for in-store. 3. Configure a matching rule, such as `Visa Credit`. 4. Include tax inputs (`originalAmountBeforeTax`, `originalTaxAmount`, `originalTotalAfterTax`) to verify surcharge-tax behavior. 5. Complete payment and confirm that the response contains non-zero `surcharge` and expected `surchargeTaxAmount`. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.