# 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).


---

# 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/transaction-api/payment-flows/surcharge.md?ask=<question>
```

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.