Koard iOS Demo App

Use the standard merchant demo for login, active-location selection, reader preparation, sale/preauth, tips, refunds, and receipts. These documentation samples target iOS SDK 1.0.21. The demo obtains KoardSDK through Swift Package Manager from the published https://github.com/koardlabs/koard-ios.git package. No local SDK source checkout or manually installed framework is required.

Set up the demo

Clone koardlabs/demos and open its ios directory:

git clone https://github.com/koardlabs/demos.git
cd demos/ios
cp KoardMerchantSDK-Demo/Config.plist.template KoardMerchantSDK-Demo/Config.plist

Edit KoardMerchantSDK-Demo/Config.plist with your SDK API key for each environment:
```
<dict>
    <key>UAT</key>
    <dict><key>apiKey</key><string>YOUR_UAT_API_KEY</string></dict>
    <key>PRODUCTION</key>
    <dict><key>apiKey</key><string>YOUR_PROD_API_KEY</string></dict>
</dict>
```
Obtain keys from the developers page in UAT or Production. Keep the real plist out of source control. Enter the merchant code and PIN on the app's login screen; they are not plist settings.
Open ios/KoardDemo.xcodeproj from the repository root. In the project's Package Dependencies, set koard-ios to Exact Version 1.0.21, then resolve packages. The public demo checkout may still pin 1.0.20; update that pin before using metadata or SDK reset examples.
Select Koard Demo (UAT) for testing. Koard Demo (Production) uses production credentials and can route real payments. The scheme selects the corresponding plist section for Run and Archive.

CocoaPods alternative

The published 1.0.21 tag also contains KoardSDK.podspec. The demo uses SPM by default; to use CocoaPods instead, remove the SPM KoardSDK product from the app target and its package dependency before adding this Podfile in demos/ios:

platform :ios, '17.0'
project 'KoardDemo',
  'Debug' => :debug,
  'Release' => :release,
  'UAT' => :debug,
  'Production' => :release

target 'KoardMerchantSDK-Demo' do
  pod 'KoardSDK', :git => 'https://github.com/koardlabs/koard-ios.git', :tag => '1.0.21'
end

Run pod install, then open KoardDemo.xcworkspace. Use either SPM or CocoaPods for the app target so KoardSDK is linked once. This is a tagged Git pod; it does not require a local SDK checkout. See Installing the SDK for both dependency options.

Run the standard checkout flow

Use a supported physical iPhone with the required Tap to Pay entitlement and Sandbox Apple Account for UAT. A simulator can display UI but cannot perform a card tap.

Log in with the merchant's code and PIN.
Open Settings and choose that merchant's active location. Its linked terminal determines payment routing. Display the choice in Settings and on the payment screen; revalidate saved choices after login or a merchant change.
Prepare the reader. If the account is unlinked, present an explicit action to accept the Tap to Pay terms, await linkAccountAsync(), then prepare again.
Enter the amount, select sale or preauth, and tap a test card. Persist the operation ID before calling the SDK.
Inspect the returned transaction. Handle partial approval, surcharge confirmation, pending, declined, and canceled outcomes before showing a receipt. Preauth authorizes a hold; capture is a separate operation.
Use transaction details for capture, refund, reversal, tip adjustment, and receipt delivery where supported by the merchant's processor.

The Running Payments samples follow this checkout sequence. They poll the SDK's public reader status, leave the reader event subscription to the SDK, and inspect the actual transaction returned by each operation. See Transaction Metadata and SDK Lifecycle for 1.0.21 features.

Transaction Metadata

Installing the SDK