Surcharging Guide
How the credit-card surcharge program works — enablement, state rules, and where the amounts appear.
Surcharging adds the card processing fee to the cardholder's total. On Cresora it is a per-merchant program: once enabled, the platform computes the surcharge server-side — there is no per-request opt-in field.
Cresora maintains a per-state rule table (prohibited / capped / disclosure text) and applies it at charge time using the merchant's state. As of this writing the table treats CA, CO, CT, ME, MA and OK as prohibited; other states apply a cap (typically 3%) and, where required (e.g. NY), a mandatory disclosure line. The table follows counsel and can change — the platform's answer at charge time is authoritative, and you can query it (below). Consult your own counsel for your obligations; Cresora does not provide legal advice.
How a surcharge is applied
- Enablement is per merchant, via the fee-settings API:
PUT /api/v1/merchants/{merchantId}/fee-settings/surcharge(permissionmerchant:update). A surcharge program and a convenience-fee program are mutually exclusive — enabling one with the other active returnsfee_program_conflict. - Computation is server-side, on cardholder-initiated charges only: a direct
SALEwithuse_type: ONE_TIME_FUTURE, and hosted-page payments. Merchant-initiated charges (RECURRING,INSTALLMENT,UNSCHEDULED_COF) are billed as-is, never surcharged. - Debit cards are never surcharged. The platform classifies the card's funding type
and omits the surcharge on debit — there is no request field to control this and no
surcharge_omitted_reasonfield; a debit charge simply carriessurcharge_amount: "0.00".
There is no surcharge: true request property. Request bodies reject unknown fields,
so sending one fails with 400 rather than doing nothing.
Where the amounts appear
Responses carry the breakdown as decimal strings:
{
"amount": "100.00",
"surcharge_amount": "3.00",
"total_amount": "103.00"
}On a hosted-page session the same fields appear on the session
(amount, surcharge_amount, convenience_fee_amount, total_amount — at most one of
the two fee fields is non-zero), and the hosted page displays the surcharge line to the
payer before they confirm.
Asking before you charge
To know whether a surcharge would apply — for your own checkout display, before any tokenization — use the preview endpoint:
POST https://api.cresoracommerce.ai/api/v1/surcharge/previewIt returns applicable (and a reason when not applicable — e.g. a prohibited state),
plus the rate that would be used. The state rule table itself is readable at
GET /api/v1/surcharge/rules.
Disclosure
Where a state requires disclosure, the rule table carries the required text and the hosted page shows it automatically. If you run your own checkout ahead of a direct-API charge, display the surcharge line before the payer confirms:
Subtotal: $100.00
Surcharge (3% — credit card fee): $3.00
Total: $103.00