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.

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.

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.

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".

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.

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "amount": 20000,
  "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku"
}

For an Authorize.net token, send tokenSource and tokenData instead of token.

{
  "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.

{
  "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.