iOS Quickstart

Run a first standard merchant checkout in UAT using iOS SDK 1.0.21. This path uses the public demo with Swift Package Manager; it does not require a local SDK source checkout.

1. Prepare the Merchant

Follow Merchant Setup in the Dashboard or Merchant Setup via API. You need a merchant, a terminal with assigned UAT processor credentials, a linked location, merchant code/PIN, and the SDK client key assigned for your app.

Check: the location and terminal belong to the merchant you will log into, and the processor configuration matches your assigned test credentials.

2. Prepare the iPhone and Entitlement

Use a supported physical iPhone running iOS 17.4+ and Xcode 16.3 or later. A simulator can display app UI but cannot perform a contactless tap.

1. Request and configure the Tap to Pay entitlement for your app's Bundle ID and signing team.
2. Set up a dedicated Sandbox Apple Account on the test iPhone.
3. Enable iOS Developer Mode for the development build and use a provisioning profile that includes the device and capability.

Check: your signed development app has the approved entitlement. Changing the Bundle ID or provisioning profile can invalidate that setup.

3. Configure and Run the Public Demo

Follow Demo Setup to clone koardlabs/demos, open ios/KoardDemo.xcodeproj, and configure the UAT SDK client key in Config.plist.

Use Exact Version 1.0.21 for the koard-ios package, resolve its KoardSDK product, and select Koard Demo (UAT). Enter the merchant code/PIN on the app's login screen; they are not plist settings. Keep the populated plist out of source control.

The demo guide includes a tagged Git CocoaPods alternative. The installation guide covers integrating the published dependency into your own app.

Check: the demo builds on the physical iPhone with UAT selected and package 1.0.21 resolved.

4. Log In and Choose the Active Location

Log in with the merchant's code/PIN. In Settings, choose the intended location and show it on the payment screen. Revalidate a remembered choice after login or a merchant change.

Your own app follows Authenticate the Merchant and Set Location. Initialize the SDK before login; block checkout until the selected location has a linked terminal.

5. Link the Account and Prepare

Prepare the reader after login and location selection. If prepare() reports accountNotLinked, offer an explicit Accept Tap to Pay terms action, await linkAccountAsync(), and prepare again. A failed or declined linking attempt keeps checkout blocked.

Use Prepare a Card Reader Session. The SDK owns its reader-event subscription; use its public status for readiness rather than attaching another reader-event iterator.

Check: preparation succeeds and the reader is ready for the selected merchant location.

6. Take the Assigned Test Payment

Enter the assigned amount and choose sale or preauth. Use the contactless test card or sandbox wallet token from your processor/network test plan. Generic keyed PAN/CVV values are not contactless test fixtures.

For your own app, save the operation ID before calling a method that accepts eventId, then use the canonical sale and response handling. A preauth is a hold, not a captured sale. Handle partial approval, surcharge confirmation, decline, cancellation, and pending outcomes before showing a receipt.

7. Verify the Outcome

Check the transaction in Koard UAT. Compare its merchant, location, status, amount, and returned identifiers with the app's result.

If the response is lost, follow Outcome Recovery; do not submit a second sale automatically. Verify signed webhook handling and the processor's settlement flow before considering integration testing complete.

Next Steps

• Integrate payments in your app, including active-location settings and readiness.
• Add order references with Transaction Metadata.
• Follow Production Configuration, App Store Launch, and the Launch Checklist.