# 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 **overridden per location (branch)**. At checkout, customers see the fee before paying; after payment, the **transaction amount** includes the surcharge, and **refunds** follow the policy you choose. ### 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** unless a location has its own saved config. * **Branch (location)-level** settings **override** the merchant default for that branch only. * **Resolution order:** branch surcharge row present → use branch; otherwise → merchant. #### What gets surcharged Rules are evaluated against the **payment method** the customer selects (gateway, card brand, wallet, ACH, etc.). The first row in the rules table that matches **gateway**, **surcharge target**, and optional **minimum transaction** conditions wins. #### Default rule: Unrecognized funding type (card gateways) When your provider catalog includes at least one credit-card gateway, the surcharge editor adds a fixed first rule whose target is Unrecognized funding type. * That rule applies when the customer chooses card pay but the service has not managed to classify credit vs debit. * Gateway is shown as a dash (—) and applies across credit card gateways for that merchant/location scope (not tied to one processor row). * You configure percentage or fixed, Apply to, etc., like any other rule. This row is reserved: you cannot remove it while card gateways exist in the catalog. * Add additional rules below for specific brands (Visa Credit, Mastercard Debit, etc.) once the gateway exposes those targets. If the catalog does not include credit card processing, this default row is not injected. #### Refund policy (two modes) * **Full refund** — Refunding returns **purchase amount + surcharge** (subject to your refund UI and processor behavior). * **Partial refund** — Customer receives back **only the original purchase amount**; the **surcharge is not refunded** to the customer. Refund flows cap the refundable amount accordingly. ### Partner Platform (SensePass Partners) Use the **Surcharge Configuration** screen in the Partner web app, Located under Management/Surcharge. #### Merchant vs branch behavior * **Merchant scope** — Edits apply to the **business default** for every location that does not have a branch override. * **Branch scope** — If the location **inherits** merchant settings, you may need to turn on **“Override Merchant Surcharge Configuration”** before editing. Saving creates a **branch-only** stored config. * **Deleting** branch surcharge (via API) makes that location **fall back** to merchant settings again. #### Configuration sections (UI) **1. Enable surcharging** Master toggle. When off, surcharge rules are ignored for that effective scope. **2. Surcharge display name** Customer-facing label for the fee (e.g. "Processing Fee", "Card Fee", "Convenience Fee", or "Surcharge"). Shown on hosted checkout and on receipts when the platform uses this metadata. **3. Surcharge is taxable** When enabled, the surcharge amount is treated as **taxable** in flows that respect this flag. **4. Refund configuration** * **Full refund** — Customer receives original amount **and** surcharge back when you issue a full refund. * **Partial refund** — Customer receives **only** the original purchase amount; surcharge is **retained** per policy. **5. Surcharge rules (table)** Each **rule** includes: | Column | Meaning | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Gateway** | Which processor/gateway this rule applies to (from your catalog). A pinned row may apply where **credit vs debit is unknown** until BIN data exists (“Unrecognized funding type”). | | **Surcharge target** | Specific network or method (e.g. Visa Credit, Mastercard Debit, Apple Pay, Google Pay, ACH), or **all sources** on that gateway where applicable. | | **Type** | **Percentage** of the applicable base amount (+service fee if exist), or **Fixed** amount in the merchant **currency**. | | **Value** | The percentage or fixed amount. Fractional values depend on currency settings. | | **Apply to** | **All** transactions matching this rule, or **Transactions ≥** a **minimum base** amount (same currency). | | Add or remove rules with **+ Add Rule** / row actions. Rules are evaluated in product-defined order with **first match** semantics for display and charging. | | | The first row may be locked when card gateways exist: target Unrecognized funding type, with gateway shown as —. That is the default surcharge rule for generic card flows when funding type is unknown; match it intentionally with your percentage/fixed and Transactions ≥ settings before adding brand-specific rows. | | **6. Preview** * “Customer payment page preview” (placeholder + note) appears only when a location is selected in the header (Branch/Location scope). * “Preview calculator” (amount, gateway, surcharge target, subtotal / fee / total) is a separate block and is not limited to branch scope — it shows whenever the main surcharge form is visible (merchant-wide or branch). #### Saving Saving persists JSON to **business settings** (merchant) or **branch settings** (location), depending on scope. ### Hosted payment page (SensePass checkout) On the hosted payment / order summary experience: * When surcharge is enabled and a rule applies, customers see a fee line (label from Surcharge display name) for the selected or generic card row as appropriate. * For credit card before the card is fully identified, the UI may show a range or safe upper bound derived from rules until funding type is known. No separate merchant action is required beyond Partners configuration — the page consumes effective surcharge config for the transaction’s merchant/branch. ### Business Dashboard For merchants using the Business dashboard: * Transaction list — Surcharge can appear as a dedicated column when enabled. * Transaction details / payment rows — Shows surcharge amount and whether it is refundable under the configured policy. * Refunds — Under partial refund policy, refund amounts are capped so customers cannot reclaim the surcharge portion; copy in the refund dialog explains the limit. --- # Agent Instructions: 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: ``` GET https://docs.sensepass.com/sensepay/partner-api/flows/surcharge.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.