> 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/partner-api/flows/surcharge.md). # Surcharge ### Surcharge configuration Surcharges let merchants pass card or payment-method processing costs to the customer. Configuration is stored per merchant (business default) and can be replaced per location (branch). At checkout, customers see the fee before paying. After payment, the transaction amount includes the surcharge and any surcharge tax. Refunds follow the policy you choose. Charge-time rules, request fields, and the `surcharge` response are documented in [Surcharge (Transaction API)](https://docs.sensepass.com/sensepay/transaction-api/payment-flows/surcharge). #### Who this guide is for | Audience | What you use | | -------------------- | --------------------------------------------------------------------------- | | Partners / merchants | Partner Platform — configure rules, refunds, and labels. | | Shoppers | Hosted payment page — fees shown on the order summary before payment. | | Finance / operations | Business Dashboard — surcharge on transactions, details, and refund limits. | #### Concepts **Effective configuration** * Merchant-level settings apply to all locations that do not have their own saved config. * A branch (location) row replaces the merchant config for that branch. It does not merge with it. * Resolution order: branch surcharge row present → use the branch row; otherwise → merchant. **What gets surcharged** Each rule is for one gateway. **All sources** is an empty target on that gateway. It does not apply to other gateways. Matching: 1. The rule gateway must be the payment gateway. A rule with no gateway never matches. **Any processor** matches every gateway. 2. An exact target (for example Visa Credit) beats an **All sources** row on the same gateway, even when All sources is higher in the table. 3. Among rows with the same target, the first row wins. 4. **Transactions ≥** is inclusive. The base must be greater than or equal to the amount you enter. For cards, the value you enter is a ceiling. Checkout and capture can charge less. See What checkout charges. **Refund policy (two modes)** * **Full refund** — The dashboard can refund any amount up to the captured total. That total includes the surcharge and surcharge tax. SensePass does not split the refund into sale versus fee. * **Partial refund** — The customer can receive only the original sale total (the amount before surcharge). The surcharge and the surcharge tax stay with the merchant. The refund dialog caps the amount and explains the limit. ### Partner Platform (SensePass Partners) Open **Surcharge Configuration** in the Partner web app, under Management / Surcharge. Pick the merchant in the header. Leave the location empty to edit the merchant default. Pick a location to edit that branch. #### Merchant vs branch behavior * **Merchant scope** — Edits apply to every location that does not have a branch row. * **Branch scope, inheriting** — The location uses the merchant config until you turn on **Override Merchant Surcharge Configuration**. Saving then stores a branch-only config. * **Branch scope, already overridden** — Edits apply to this location only. * **Inherit from business** — Shown when this location has its own row. It deletes that row. The location uses the merchant config again. #### Configuration sections (UI) **1. Enable surcharging** Master toggle. When off, rules for this merchant or this location are ignored. No surcharge is stored on the transaction. **2. Location type** * **E-commerce** — Partners does not set a state. The customer state comes from checkout (ZIP or state). Card fees need a US state that SensePass knows. ACH, Samsung Pay, and Google Pay card-on-file do not. * **In-store** — You pick **Store state (US)**. That state is required to save. It is the state used for card rules. The customer's billing state does not override it. `DC` is in the dropdown and is not in the surcharge state table, so an in-store `DC` location does not keep that state for the fee. Card resolution then continues as e-commerce and asks for a customer ZIP. **3. Surcharge display name** The label customers see (for example "Processing Fee", "Card Fee", "Convenience Fee", or "Surcharge"). The form starts as "Surcharge". Hosted checkout and receipts use the saved label. If the saved label is blank, checkout uses "Processing Fee". **4. Refund configuration** * **Full Refund** — Refund the complete amount including surcharge. The UI copy is "Customer receives back: Original amount + Surcharge". The refundable balance is the captured total, which also includes surcharge tax when tax was added. * **Partial Refund** — Refund only the original amount. The UI copy is "Customer receives back: Original amount only (surcharge and surcharge tax are retained)". **5. Surcharge rules** | Column | Meaning | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Gateway | Processor this rule applies to. | | Surcharge target | Visa Credit, Mastercard Credit, Apple Pay Credit, Google Pay, Samsung Pay, ACH, the matching debit rows, or **All sources** on that gateway. | | Type | **Percentage** of the applicable base, or **Fixed** amount in the merchant currency. | | Value | The percentage (0–100) or the fixed amount. | | Apply to | **All**, or **Transactions ≥** a minimum base in the same currency. The comparison is inclusive. | Use **+ Add Rule** and the row remove action. A debit or prepaid target can be saved. Those cards are never charged a fee. Unknown card funding is never surcharged. A percentage on a card can be reduced by state law, the card network, and the merchant's processing cost. A fixed card fee is reduced the same way when it is above that ceiling. **6. Customer payment page preview** Shown only when a location is selected in the header. It lists the fee label checkout will show for each configured target on that location. It is not the amount a specific card will be charged after state and network caps. **7. Preview calculator** Shown for merchant scope and for branch scope. Enter an amount, gateway, and surcharge target. It shows subtotal, fee, and total from the matching rule only. The calculator does not apply US state caps, card-network caps, merchant processing cost, equal treatment, or registration. A 4% rule can show 4% here and charge 2%, 3%, or $0 at payment. #### Saving **Save Configuration** writes the JSON to business settings (merchant) or branch settings (location). **Reset** restores the form. **Inherit from business** removes the location row. ### What checkout charges The hosted payment page uses the effective config (branch row, otherwise merchant). No extra merchant step is required. * Before the card is identified, credit card can show a range from 0% up to the capped maximum. That range is a disclosure. It is not the charged amount. * After the card is known, the fee follows the matching rule, then the caps in the [Transaction API surcharge guide](https://docs.sensepass.com/sensepay/transaction-api/payment-flows/surcharge). * Credit cards can be surcharged. Debit and prepaid are $0 even when a debit rule exists. * Apple Pay uses the underlying card, then the Apple Pay credit or debit rule, then **All sources**. The fee is also kept inside the total the wallet sheet approved. * Google Pay device tokens with unknown card funding are $0. Google Pay card-on-file, Samsung Pay, and ACH use the merchant rule only. State bans and network caps do not apply to those three, and they do not need a customer ZIP. * If merchant processing cost is not configured, American Express, Discover, and cost-cap states (Georgia, Nebraska, Nevada, New Jersey, New York, South Dakota) charge $0 on cards. Visa and Mastercard still apply 3% and 4%. * Surcharge tax is added only when the state says the fee is taxable. Colorado does not tax the surcharge. Other US states in the table do. Platform tax on the sale is not recalculated. ### Business Dashboard * Transaction list — Surcharge can appear on the amount when a fee was stored, including a $0 decision. * Transaction details — Surcharge amount, surcharge tax, display name, and whether the fee is refundable. * Refunds — Partial policy caps the refund at the original sale total so the customer cannot reclaim the surcharge or the surcharge tax. The refund dialog states the limit. --- # 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/partner-api/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.