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.

