Apple Best Practices and Guidelines

Overview

These integration patterns use the published Koard iOS SDK 1.0.21 for merchant Tap to Pay payments. Let the SDK manage Apple's reader; use its public readiness and payment methods in your app.

Apple's Dual Review Process

1. Tap to Pay Review

Apple's Tap to Pay team reviews your in-app experience when you request the distribution entitlement. Going to Production on iOS lists what it checks. The entitlement setup guide covers access and provisioning.

2. App Store Review

Use Going to Production on iOS to prepare the reviewer flow and the correct environment build. Consult Apple's current App Review Guidelines for submission requirements.

User Experience Best Practices

Feedback and User Actions

Show the active merchant location in Settings and on the payment screen. Require an explicit selection of a location belonging to the authenticated merchant with a usable linked terminal. Explain whether the payment is a sale or a preauth hold, show the final amount, and prevent duplicate payment actions while work is in progress.

Error Handling Best Practices

Keep background preparation feedback inline. An accountNotLinked error requires a visible terms-acceptance action; do not launch linking from a background retry. Handle customer cancellation separately from a decline or an unknown payment outcome. Preserve the saved operation ID for recovery after network failures.

ProximityReader Framework Best Practices

Reader Management

Initialize once, log in, select the active location, and prepare before the first payment. The demo app reads KoardMerchantSDK.shared.status; the SDK owns the reader event subscription. Do not add a competing readerEvents iterator or construct a separate ProximityReader session alongside the SDK.

A preparation coordinator keeps app-triggered preparation sequential and surfaces errors:

import Combine
import KoardSDK

@MainActor
final class PaymentReadiness: ObservableObject {
    @Published private(set) var isPreparing = false
    @Published private(set) var isReady = false
    @Published private(set) var needsAccountLinking = false
    @Published private(set) var message = "Reader not ready"

    func prepare() async {
        guard !isPreparing else { return }
        isPreparing = true
        defer { isPreparing = false }
        do {
            try await KoardMerchantSDK.shared.prepare()
            let status = KoardMerchantSDK.shared.status
            isReady = status.isReady
            needsAccountLinking = false
            message = status.info
        } catch KoardMerchantSDKError.accountNotLinked {
            isReady = false
            needsAccountLinking = true
            message = "Accept Tap to Pay terms to continue"
        } catch {
            isReady = false
            message = error.localizedDescription
        }
    }

    // Call only from the operator's explicit terms-acceptance action.
    func acceptTerms() async {
        guard !isPreparing else { return }
        isPreparing = true
        do {
            try await KoardMerchantSDK.shared.linkAccountAsync()
            isPreparing = false
            await prepare()
        } catch {
            isPreparing = false
            isReady = false
            needsAccountLinking = true
            message = error.localizedDescription
        }
    }
}

Call these methods after login and location selection. Monitor public status while the view is visible using the cancelable polling example. Disable payments during preparation, merchant/location changes, and SDK cleanup.

Secure Payment Processing

Use the SDK's sale and preauth calls to obtain the encrypted reader data and route the request. Amount arguments are integer minor currency units. Inspect response.transaction before displaying success; partial approval, surcharge confirmation, and pending outcomes need separate handling. See Running Payments.

Security Best Practices

Data Protection and Privacy

Persist order references, operation IDs, transaction IDs, and approved receipt data needed by your app. Keep privileged API keys on your backend. Never put card data, PINs, session tokens, or credentials in metadata or application logs. Use the intended scoped SDK client key in the mobile app.

Entitlement Verification

Configure Tap to Pay entitlements and provisioning for the app's bundle ID. Test on a supported physical iPhone; a successful simulator build does not validate a reader entitlement or a real tap. isReaderSupported describes reader support, not proof that merchant linking and preparation succeeded.

UI/UX Design Guidelines

Payment Flow Design

Keep the amount, currency, active location, and sale/preauth mode visible. Obtain any required surcharge decision using the returned disclosure and final total. Show partial approval before collecting the remainder on another card. An authorized hold must not be presented as captured or settled.

Progress and Loading States

Display preparation and transaction progress without blocking the main thread. Keep the payment button disabled during active work. Poll readiness only while the view is visible and cancel the polling task on navigation; do not accumulate untracked event listeners.

Testing and Validation

Comprehensive Testing Strategy

Exercise login, merchant changes, invalid saved locations, reader preparation, declined linking, sale, preauth, partial approval, surcharge decisions, refunds, and cancellation. Test uncertain outcomes and transaction recovery without automatically submitting a second charge. Use the correct environment and test cards on physical hardware.

TestFlight Preparation

Archive with the intended environment scheme and matching SDK client key. Verify the same signed build, entitlement, merchant location, and reader flow that testers will use.

App Store Review Preparation

Documentation Requirements

Provide clear reviewer steps for authentication, location selection, terms acceptance, and taking a payment. Explain any test-account or device setup needed to reach those screens. See Going to Production on iOS.

Review Checklist

  • The archive uses the intended environment and provisioning.
  • The active location and transaction amount are visible before payment.
  • Linking, preparation, cancellation, and decline flows provide actionable feedback.
  • Receipts reflect the returned transaction state and actual amounts.
  • Testing includes a supported physical device.

Performance Optimization

Memory Management

Cancel screen-owned monitoring tasks when leaving the screen. Reuse the SDK singleton and let it own reader sessions. Complete active payment/preparation work before logout or deinitialization.

Network Optimization

Prepare after merchant and location setup to move reader readiness work ahead of the first payment. Reuse the saved operation ID for supported outcome recovery; do not invent a new payment after a timeout. Backend-operation success must be determined from the returned transaction, not solely from a completed network call.

Resources and References

Apple Documentation

Koard Resources

Additional Support

Contact Koard Developer Support with the SDK version, environment, transaction/operation IDs, and a sanitized description of the failure.