Incremental Auth

Incremental authorization increases the hold amount on an existing preauth. Common uses:

• Adding a custom surcharge after BIN lookup
• Increasing the hold for additional items or services
• Adjusting the authorization before capture

Basic Incremental Auth

iOS:

let response = try await KoardMerchantSDK.shared.auth(
    transactionId: transactionId,
    amount: 2000              // increase hold by $20
)

Android:

sdk.incrementalAuth(
    transactionId = transactionId,
    amount = 2000
)

Incremental Auth with Surcharge Breakdown

When adding a custom surcharge via incremental auth, include the surcharge details in the breakdown. The surcharge percentage is applied to the full transaction amount (subtotal + tax + tip):

iOS:

let baseAmount = 10000 + 875 + 2000  // subtotal + tax + tip = 12875
let surchargeRate = 0.035
let surchargeAmount = Int(Double(baseAmount) * surchargeRate)  // 451

let surchargeBreakdown = PaymentBreakdown(
    subtotal: 0,
    taxAmount: 0,
    tipType: .fixed,
    surcharge: PaymentBreakdown.Surcharge(
        amount: surchargeAmount,
        percentage: surchargeRate
    )
)

let response = try await KoardMerchantSDK.shared.auth(
    transactionId: transactionId,
    amount: surchargeAmount,
    breakdown: surchargeBreakdown
)

Android:

val baseAmount = 10000 + 875 + 2000  // 12875
val surchargeRate = 0.035
val surchargeAmount = (baseAmount * surchargeRate).toInt()  // 451

val surchargeBreakdown = PaymentBreakdown(
    subtotal = 0,
    taxAmount = 0,
    tipType = "fixed",
    surcharge = Surcharge(
        amount = surchargeAmount,
        percentage = surchargeRate
    )
)

sdk.incrementalAuth(
    transactionId = transactionId,
    amount = surchargeAmount,
    breakdown = surchargeBreakdown
)

Custom Surcharging via BIN Lookup

The most common use of incremental auth is the BIN-based surcharging workflow:

1. Preauth with surcharge: Surcharge(bypass: true) to get the card BIN
2. BIN lookup to determine if the card is credit (surchargeable) or debit (not surchargeable)
3. Incremental auth to add the calculated surcharge amount
4. Capture at the full amount with the complete breakdown

Reminder: Surcharges must not be applied to debit cards. Always verify the card type from the BIN before adding a surcharge via incremental auth.

Parameters

Note: The iOS SDK method is auth() while the Android SDK method is incrementalAuth().

See Also

• Preauth — Initial authorization hold
• Capture — Finalize after incrementing
• Surcharging — BIN-based custom surcharge workflow