> 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/transaction-api/payment-flows/surcharge.md). # Surcharge ## Surcharging integration guide SensePass applies surcharges automatically within state and card-network limits. Always send the **base amount**, before surcharge. SensePass adds the correct surcharge during authorization and capture. ### Prerequisites Surcharge is configured per merchant. A location can override the merchant configuration. A surcharge applies only when every requirement below is met. | # | Requirement | Where it is set | | - | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | 1 | Surcharging is enabled for the location. | **Partner Dashboard** → **Location** → **Surcharge** | | 2 | A rule matches the payment method. Use an `All sources` rule or a brand-specific rule. | **Partner Dashboard** → **Surcharge** → **Surcharge Rules** | | 3 | The card is a credit card. Debit and prepaid cards are never surcharged. | Determined from the card BIN | | 4 | The customer's region permits surcharging. | Billing ZIP for e-commerce; location state for in-store | When `All sources` and brand-specific rules both match, the most specific rule applies. Rules can use a percentage or fixed amount. A percentage is a ceiling request. SensePass applies the lowest permitted state or network rate. ### When surcharge is $0 SensePass evaluates four gates. If any gate fails, surcharge is `$0`. The transaction can still be approved for its base amount. | Gate | Question | Surcharge is $0 when | | ------ | --------------------------------------------- | ---------------------------------------------------------- | | **G1** | Is surcharging enabled for this location? | The location toggle is off. | | **G2** | Is the card a credit card? | The card is debit, prepaid, or the BIN cannot be resolved. | | **G3** | Is there a matching rule? | Neither `All sources` nor a brand-specific rule matches. | | **G4** | Does the customer's state permit surcharging? | The billing ZIP resolves to a prohibited state. | {% hint style="warning" %} An unrecognized sandbox BIN resolves to unknown funding and fails G2. This remains true even when the authorization response later reports `Credit`. Test with a card whose BIN resolves to credit funding. {% endhint %} ### Regional support Surcharging currently supports US transactions only. No surcharge applies to non-US billing regions. SensePass maintains the active state rules. The backend rule set is authoritative. | Status | State codes | Effect | | ----------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- | | **Prohibited** | `CA`, `CT`, `ME`, `MA`, `PR` | No surcharge applies. | | **Capped (fixed %)** | `CO` (2%), `MT` (3%), `MD` (4%), `MN` (5%) | The rate is reduced to the state maximum. | | **Capped (cost-based)** | `GA`, `NE`, `NV`, `NJ`, `NY`, `SD` | The rate is reduced to processing cost. In `SD`, it is the lower of 4% or cost. | | **Disclosure-only** | `TX`, `VA`, `RI`, `WY` | No numeric state cap. Network caps still apply. | | **Permitted** | All other US states | Your configured rate applies, subject to network caps. | ### Funding type and wallets * Credit cards can be surcharged, subject to state and network caps. * Debit and prepaid cards are never surcharged. This applies when debit runs as credit. * Digital wallets inherit the underlying card's funding type. * An unresolved BIN fails closed. No surcharge applies. ### Network caps SensePass always applies card-network caps. | Network | Maximum surcharge | | ---------------- | --------------------------------------- | | Visa | Lower of merchant processing cost or 3% | | Mastercard | Lower of merchant processing cost or 4% | | American Express | Merchant processing cost | | Discover | Merchant processing cost | ### Integration flows #### Send the base amount Always send the base amount. Do not pre-add or reverse-engineer the surcharge. All request amounts are in cents. `100` represents `1.00`. The `/transactions/pay` endpoint accepts cents only. #### Payment (sale) Create a transaction with `POST /transactions/init` and `methodType: "Payment"`. The customer completes the hosted-page or SDK payment. SensePass resolves, displays, and applies an eligible surcharge. ```json POST /transactions/init { "timeOut": 600, "amount": 20000, "isCent": true, "currency": "USD", "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm", "callbackURL": "https://example.com/callback", "methodType": "Payment" } ``` `amount` is the base amount in cents. The transaction or callback returns `surcharge` when a fee applies. #### Authorize and capture Send the base amount at authorization and capture. The transaction returns `surcharge` when a fee applies. Create the authorization with `POST /transactions/init` and `methodType: "Authorize"`. ```json POST /transactions/init { "timeOut": 600, "amount": 20000, "isCent": true, "currency": "USD", "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm", "callbackURL": "https://example.com/callback", "methodType": "Authorize" } ``` After payment, retrieve the authorization token from `paymentDetails.token` in the callback. Capture with `POST /transactions/pay`. Capture once for the full amount or multiple times for smaller amounts. The combined captures cannot exceed the authorized amount. ```json { "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm", "amount": 20000, "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku" } ``` For an Authorize.net token, send `tokenSource` and `tokenData` instead of `token`. ```json { "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm", "amount": 20000, "tokenSource": "Authorize.net", "tokenData": { "profile_id": "12121212", "payment_id": "32323232", "auth_code": "ABC123" } } ``` Related endpoints: * Re-authorize: `POST /transactions/authorize` * Void: `POST /transactions/void` * Close authorization: `POST /transactions/{transactionNumber}/closeAuth` (Cardknox only) An uncaptured authorization is released after timeout or void. #### Tokenization Create a token through the hosted flow using `methodType: "Tokenize"` or `"Capture+Tokenize"`. The callback returns the token at `paymentDetails.token`. For PCI environments, use `POST /transactions/tokenize` with `apiKey` and `creditCardDetails[]`. Charge a token with `POST /transactions/pay`. Surcharge resolves at charge time using stored card metadata. Eligible credit-card tokens surcharge normally. Unresolved funding is not surcharged. Validate a token with `POST /transactions/token-validation`. This verifies current chargeability and returns AVS/CVV results. ### Surcharge in responses SensePass persists surcharge details on the transaction. API payloads expose a read-only `surcharge` object after a successful charge. If no surcharge applies, the `surcharge` object is omitted. This indicates that an eligibility gate resolved the amount to `$0`. #### Where the object appears | Channel | Notes | | --------------------------- | -------------------------------------------------------------------------------- | | Get transaction | Transaction detail and filtered payloads include top-level `surcharge` metadata. | | Successful payment response | Approved payments can include `surcharge`. | | Merchant callback | Included when `callbackURL` is set on the transaction request. | The stored metadata key is `paymentSurcharge`. Responses normally expose a parsed copy as `surcharge`. Prefer `surcharge` when both exist. #### `surcharge` object | Field | Type | Description | | --------------------- | ---------------------------------- | ------------------------------------------------------------ | | `amount` | number | Surcharge amount in the transaction currency. | | `baseBeforeSurcharge` | number | Amount used to calculate the fee. | | `totalAmount` | number | Total amount, including the fee. | | `refundable` | boolean | `false` retains the surcharge on refunds. `true` refunds it. | | `displayName` | string | Customer-facing label, such as `Processing fee`. | | `detailLineShort` | string | Short receipt or UI line. | | `summaryDescription` | string | Longer customer-facing description. | | `surchargeTarget` | string (optional) | Internal target, such as `surcharge:visa_credit`. | | `type` | `percentage` \| `fixed` (optional) | Applied rule type. | | `percentage` | number (optional) | Configured percentage rate. | | `fixedAmount` | number (optional) | Configured fixed fee. | ```json { "surcharge": { "amount": 2.5, "baseBeforeSurcharge": 100, "totalAmount": 102.5, "refundable": false, "displayName": "Processing fee", "detailLineShort": "Processing fee 2.5%", "summaryDescription": "A processing fee applies to credit card payments.", "surchargeTarget": "surcharge:visa_credit", "type": "percentage", "percentage": 2.5 } } ``` ### Refunds Refunds include the proportional surcharge by default. A merchant or location can instead retain the surcharge on refunds. `surcharge.refundable` reflects that policy. When `false`, downstream refunds are capped to exclude the surcharge. When `true`, the full captured amount is refundable. ### Troubleshooting Work through the eligibility gates in order: 1. Confirm surcharging is enabled for the location. 2. Confirm the card BIN resolves to credit funding. 3. Confirm that `All sources` or a brand-specific rule matches. 4. Confirm that the billing ZIP resolves to a permitted state. 5. If all gates pass, confirm whether a state or network cap reduced the rate. Check the payment or transaction response. An omitted `surcharge` object confirms a gate resolved the surcharge to `$0`. When present, `surchargeTarget` shows the matched rule. ### Sandbox testing 1. Use a sandbox card whose BIN resolves to credit funding. 2. Use a billing ZIP in a permitted state, such as Ohio. 3. Configure a matching rule, such as `Visa Credit`. 4. Complete payment and confirm that the response surcharge is non-zero. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sensepass.com/sensepay/transaction-api/payment-flows/surcharge.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.