Sale Transactions

Process card-present payments that authorize and capture funds in a single step.

What You Learn

When to use a sale versus other payment flows
Required fields for the iOS SDK and REST API
How to include tax, tip, and surcharge details using the updated breakdown schema
Expected response payloads from the Koard Payments API

When to Use a Sale

Use sales when the final amount is known at the moment of payment and you want to capture funds immediately. Common scenarios include retail checkout, quick-service restaurants, and fixed-price services.

Workflow	iOS SDK	REST API
Sale (tap + capture)	`KoardMerchantSDK.shared.sale()`	`POST /v4/payment`

Tap required: Sale requests must originate from a Tap to Pay on iPhone interaction (or another compliant reader). After the tap is processed, all follow-up operations (refund, void) can be done via API.

Prerequisites

Koard Tap to Pay enabled merchant
Sandbox Apple Account signed into a dedicated test iPhone
Koard API key with payments scope
Terminal configuration with surcharge settings (optional)

iOS SDK Example

let breakdown = PaymentBreakdown(
    subtotal: 10000,     // $100.00 in cents
    taxRate: 0.0875,     // 8.75% expressed as a decimal
    taxAmount: 875,      // $8.75 in cents
    tipAmount: 2000,     // $20.00 in cents
    tipType: .fixed,
    surchargeAmount: 350,  // Optional: $3.50 surcharge
    surchargeRate: 0.035   // 3.5% surcharge rate
)

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

do {
    let response = try await KoardMerchantSDK.shared.sale(
        transactionId: "order-12875",   // Optional idempotency key
        amount: 13225,                  // Total = subtotal + tax + tip + surcharge
        breakdown: breakdown,
        currency: currency,
        type: .sale
    )

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

REST API Example

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

{
  "terminal_id": "term_123",
  "amount": 13225,
  "currency": "USD",
  "breakdown": {
    "subtotal": 10000,
    "taxAmount": 875,
    "taxRate": 0.0875,
    "tipAmount": 2000,
    "tipType": "fixed",
    "surchargeAmount": 350,
    "surchargeRate": 0.035
  },
  "card_data": {
    "encrypted_data": "...",
    "encryption_type": "apple_tap_to_pay"
  },
  "transaction_id": "order-12875"
}

Breakdown Fields

The payments schema now supports surcharge data and floating-point rates:

taxRate and surchargeRate are decimals (e.g., 0.0875 for 8.75%).
taxAmount, tipAmount, and surchargeAmount remain minor units (cents).
All breakdown fields map to Transaction properties returned by the API.

Response Snapshot

Successful sale requests return a Transaction object:

{
  "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
  "status": "captured",
  "total_amount": 13225,
  "subtotal": 10000,
  "tax_amount": 875,
  "tax_rate": 0.0875,
  "tip_amount": 2000,
  "surcharge_amount": 350,
  "surcharge_rate": 0.035,
  "currency": "USD",
  "payment_method": "contactlessIcc",
  "processor": "tsys"
}

Next Steps

Refunds – Return funds to the customer if the order changes
Payment Lifecycle – See how sales fit into overall payment flows
Capture – Learn how captures differ from one-step sales