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.

Surcharge in transaction and payment responses

When a surcharge is applied to a payment, SensePass persists the details on the transaction and exposes them as a structured surcharge object on API-style payloads. You do not configure surcharge through these responses; they are read-only outputs after configuration (Partners / merchant settings) and a successful charge path.

If no surcharge was applied to the transaction, surcharge is omitted.

---

Where the Surcharge object appears

Channel	Notes
Get transaction	Transaction detail / filtered transaction payloads include a top-level surcharge property when surcharge metadata exists.
Successful payment response	On an approved payment, the response object can include surcharge when surcharge was applied for that flow.
Merchant callback (server URL)	See Callbacks below

The underlying stored metadata key is paymentSurcharge. Responses usually expose a parsed copy at surcharge for convenience. If metadata.paymentSurcharge is present as a raw string, prefer using surcharge when both exist.

---

surcharge object

Field	Type	Description
amount	number	Surcharge fee charged (in the transaction currency).
baseBeforeSurcharge	number	Amount the surcharge was calculated from (before adding this fee).
totalAmount	number	Total including surcharge (aligned with baseBeforeSurcharge + amount).
refundable	boolean	false when the merchant refund policy is partial (the surcharge portion is not returned to the customer on refunds). true when the policy is full or legacy default. Used to cap refunds in downstream flows.
displayName	string	Customer-facing label from merchant Surcharge display name (e.g. “Processing fee”).
detailLineShort	string	Short line suitable for receipts or tight UI.
summaryDescription	string	Longer descriptive text for summaries.
surchargeTarget	string (optional)	Internal target identifier (e.g. surcharge:visa_credit, surcharge:unrecognized_funding).
type	'percentage' | 'fixed' (optional)	Rule type that was applied.
percentage	number (optional)	When type is percentage, configured rate (e.g. 10 for 10%).
fixedAmount	number (optional)	When type is fixed, configured flat fee in currency units.

Merchant callback URL (after successful payment)

If you configure a server callback URL for transaction status notifications (in init transaction request body.callbackURL), surcharge is included when the callback carries the same filtered transaction payload as get-transaction:

• The surcharge object is included in the JSON request body together with the rest of the transaction fields (subject to your usual response filtering and authentication).