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.