Preauthorization Transactions

Hold funds on a customer's card while you finalize the total amount.

What You Learn

When to choose a preauthorization instead of a sale
Required fields for Koard's iOS SDK and REST API
How to use breakdown data (including surcharge) for accurate settlements
Follow-up actions to complete, increase, or void a preauth

Why Use Preauth?

Preauthorizations reserve funds without capturing them. They are ideal when the final ticket amount is unknown or when you expect adjustments after the customer leaves.

Common use cases:

Table-service restaurants that add tips after checkout
Hotels adding room charges or mini-bar fees
Equipment rentals with potential damage fees

Workflow	iOS SDK	REST API
Preauth (tap only)	`KoardMerchantSDK.shared.preauth()`	`POST /v4/preauth`

Prerequisites

Tap to Pay entitlement and Koard terminal configuration
Sandbox Apple Account on a dedicated test device
Koard API key with payments scope
Stored transaction ID strategy for idempotency

iOS SDK Example

let currency = CurrencyCode(currencyCode: "USD", displayName: "US Dollar")

do {
    let response = try await KoardMerchantSDK.shared.preauth(
        transactionId: "stay-001",
        amount: 25000,  // $250.00 hold in cents
        currency: currency,
        breakdown: PaymentBreakdown(
            subtotal: 22000,
            taxRate: 0.0875,
            taxAmount: 1925,
            tipAmount: 0,
            tipType: .fixed,
            surchargeAmount: 1075,
            surchargeRate: 0.049
        )
    )

    print("Preauth created: \(response.transactionId ?? "Unknown")")
} catch {
    print("Preauth failed: \(error)")
}

REST API Example

POST /v4/preauth
Content-Type: application/json
X-Koard-Apikey: <your-api-key>

{
  "terminal_id": "term_123",
  "amount": 25000,
  "currency": "USD",
  "breakdown": {
    "subtotal": 22000,
    "taxAmount": 1925,
    "taxRate": 0.0875,
    "tipAmount": 0,
    "tipType": "fixed",
    "surchargeAmount": 1075,
    "surchargeRate": 0.049
  },
  "card_data": {
    "encrypted_data": "...",
    "encryption_type": "apple_tap_to_pay"
  },
  "transaction_id": "stay-001"
}

Tap required: The /v4/preauth endpoint expects encrypted card data from a tap event. You cannot invoke it without a card-present transaction.

Follow-Up Operations

Capture – Collect part or all of the authorized funds
Incremental Auth – Increase the hold if the ticket grows
Reverse – Release the hold when the customer cancels
Refund – Return funds after a capture

Refer to the Payment Lifecycle guide for end-to-end flow examples.