Surcharging
Koard supports configured surcharges on eligible credit-card transactions. Eligibility, supported amounts, disclosures, and cardholder confirmation depend on the processor and merchant configuration. Do not apply surcharges to debit cards. Confirm your surcharge rules with your processor before enabling them.
Configuration Defaults
Configure the public surcharge defaults on the merchant account, terminal, or location where your account has update access:
| Field | Meaning |
|---|---|
surcharge_rate |
Whole percent units, for example 3.5 for 3.5% |
surcharge_basis |
total, subtotal, subtotal_plus_tax, or subtotal_plus_tip |
surcharge_confirmation_required |
Whether the cardholder must confirm a surcharge before the sale continues |
The first non-null setting from location, then terminal, then account applies. A null value inherits; zero rate disables the default surcharge. The default basis is total, including subtotal, tax, and tip. Do not assume every merchant uses that basis. See Tax and Tip Handling.
Calculation and eligibility
For a configured default, surcharge_basis: subtotal excludes both taxAmount and tipAmount. The other bases include exactly the components named above. Koard calculates in minor currency units and rounds to the nearest integer using half-even rounding: an exact half-cent goes to the even cent. For example, 3% of 150 cents is 4.5 cents and rounds to 4 cents. This describes the server-calculated default; a supplied fixed surcharge.amount is already an integer and is not recalculated.
The automatic surcharge gate excludes debit cards and cards classified as prepaid or unknown by Koard's BIN data. Eligibility depends on the available card classification, including upstream lookup results; do not use a credit-network brand alone as proof of eligibility.
On the Fiserv Nashville North (Global) route, an applied surcharge is included once in the authorized total and also sent in the processor's dedicated surcharge amount field. That field describes a component of the total, not an extra charge on top.
Request Overrides
A breakdown's surcharge object accepts one of:
{"amount": 451}
{"percentage": 3.5}
{"bypass": true}
amount is an integer in minor currency units. percentage uses whole percent units, so 3.5 means 3.5%, not 0.035. Never send both amount and percentage. When bypass is true, omit both. For an explicitly calculated fee, include it in the final request total and use the matching fixed surcharge amount.
For example, USD subtotal 10000 + tax 875 + tip 2000 gives a base of 12875 cents. At a 3.5% total basis, round the fee to 451 cents and send a total of 13326 cents.
iOS:
let breakdown = PaymentBreakdown(
subtotal: 10000,
taxRate: 8.75,
taxAmount: 875,
tipAmount: 2000,
tipType: .fixed,
surcharge: PaymentBreakdown.Surcharge(amount: 451)
)
let response = try await KoardMerchantSDK.shared.sale(
amount: 13326,
breakdown: breakdown,
currency: CurrencyCode(currencyCode: "USD", displayName: "US Dollar"),
eventId: eventId
)
On Android, supply Surcharge(amount = 451) in the PaymentBreakdown passed to the released SDK's sale flow. See the full Android payment flow for Activity, coroutine, and reader-event handling.
Flow 1: Sale with Cardholder Confirmation
When a sale returns surcharge_pending (iOS SDK surchargePending), show the surcharge disclosure and final amount to the cardholder and complete the supported SDK confirmation flow. Do not mark the sale captured while confirmation is pending. Inspect the confirmation's resulting status and amounts. Do not independently resend the original sale.
The confirmation arguments and reader states differ between platforms. Follow the iOS or Android flow. A preauth does not use this sale confirmation workflow.
Pending amounts, rejection and expiry
When the effective surcharge_confirmation_required is true and the calculated fee is positive, an eligible sale returns surcharge_pending with surcharge_amount and the final total_amount already calculated. A zero fee or excluded card does not require surcharge confirmation.
For Fiserv Nashville North (Global), this pending step occurs before processor authorization. Accepting through confirm(..., true) submits the payment. Declining through confirm(..., false) cancels the pending sale with status: canceled and status_reason: surcharge_declined_by_payer; there is no authorization from this pending step to reverse.
The saved confirmation context expires after 120 seconds. An attempt to accept after expiry returns status: canceled with status_reason: surcharge_expired. surcharge_expired is a reason, not a transaction status. Background cleanup can also mark stale pending sales canceled; the visible state can update later than the 120-second confirmation deadline, so do not depend on a status change at exactly two minutes.
On Android, cancelTransaction() only cancels the reader session. It does not submit a surcharge decision or reverse a backend transaction. Once you have a surcharge_pending transaction, reject it with sdk.confirm(transactionId = transactionId, confirm = false, eventId = decisionEventId) and inspect the result. See Confirming a surcharge.
Declining or expiring a pending surcharge emits transaction.cancel with the cancellation reason. Use the confirmation response or cancellation webhook to update the payment screen, and outcome recovery if the response is lost.
Flow 2: Custom Surcharge via Preauth
For a processor-approved custom surcharge flow:
- Create a preauth with
surcharge: {"bypass": true}in the breakdown. - Inspect the returned
card_typeand other supported eligibility information. The transaction response has nobinproperty. If your integration requires an external BIN lookup, use an approved data source; do not infer a BIN from masked card data. - For an eligible credit card, calculate the permitted fee using the configured basis and rounding rules.
- Where supported, increase the hold by the fee through incremental authorization.
- Capture the final total with a complete breakdown containing the fixed surcharge amount.
An incremental authorization request can omit breakdown entirely:
POST /v3/payments/{transaction_id}/auth
X-Koard-apikey: YOUR_API_KEY
Content-Type: application/json
{"amount": 451, "event_id": "YOUR_INCREMENT_EVENT_ID"}
The legacy incremental-auth breakdown does not accept a nested surcharge object. Android 1.0.7 incrementalAuth does not expose a breakdown argument either. Include the final supported breakdown at capture:
POST /v4/payments/{transaction_id}/capture
X-Koard-apikey: YOUR_API_KEY
Content-Type: application/json
{
"amount": 13326,
"event_id": "YOUR_CAPTURE_EVENT_ID",
"breakdown": {
"subtotal": 10000,
"taxAmount": 875,
"taxRate": 8.75,
"tipAmount": 2000,
"tipType": "fixed",
"surcharge": {"amount": 451}
}
}
Keep the original preauth, increment, and capture event IDs distinct and persist each before submission. Verify the increment succeeded before capturing an increased amount.
Remove a Fee Before Capture
If a fee is not permitted, remove it from the final breakdown and capture the lower supported amount. Use a surcharge bypass without amount or percentage. Remaining holds are released according to processor and issuer rules; do not promise immediate availability to the cardholder.
Follow-Up Operations
Tip adjustment does not recalculate the original surcharge. Refund and reversal treatment depends on processor rules; do not assume every processor automatically prorates a surcharge on a partial refund. Reconcile the returned amounts and processor report.
See Capture, Incremental Auth, Tip Adjust, Refund, and Idempotency.

