Installing the SDK

Install the Koard Merchant SDK to enable tap-to-pay functionality in your iOS application.

If you're ready to start developing, see our Tap to Pay configuration guide.

Get started with Koard

Step 1: Add the SDK

We recommend Swift Package Manager for most projects. If you cannot use SPM, install the SDK manually as an XCFramework instead.

Option A: Swift Package Manager (Recommended)

1. In Xcode, choose File → Add Package Dependencies…
2. Enter the package URL: https://github.com/koardlabs/koard-ios.git
3. Set the dependency rule to "Up to Next Major Version" starting from 1.0.0
4. Add the KoardSDK library product to your app target

You can also add it directly to a Package.swift:

.package(url: "https://github.com/koardlabs/koard-ios.git", from: "1.0.0")

Then list KoardSDK as a dependency of your target.

Option B: Manual XCFramework

1. Download the latest KoardSDK.xcframework.zip from the Releases page or get it directly from the team
2. Extract the ZIP file to reveal the KoardSDK.xcframework bundle
3. Drag KoardSDK.xcframework into your Xcode project (or use your target's General → Frameworks, Libraries, and Embedded Content → "+" → Add Other… → Add Files…)
4. Ensure "Copy items if needed" is checked and the framework is added to your app target

Step 2: Configure Embed Settings

When installing the XCFramework manually, embedding is crucial for the SDK to work properly in your app. (Swift Package Manager handles embedding automatically.)

1. Open your target's "General" tab under "Frameworks, Libraries, and Embedded Content"
2. Find KoardSDK.xcframework in the list
3. Change the "Embed" setting from "Do Not Embed" to "Embed & Sign"

Step 3: Verify Installation

Check Framework Integration

1. Build your project (⌘+B) to ensure there are no compilation errors
2. Verify the package or framework appears in your project navigator
3. For a manual install, check the framework is listed under "Frameworks, Libraries, and Embedded Content"

Test Basic Import

Add this import statement to one of your Swift files to verify the SDK is accessible:

import KoardSDK

If the import succeeds without errors, your installation is working correctly.

Step 4: Initialize the SDK

Once the SDK is installed, initialize it early in your app lifecycle with your KoardOptions and API key:

import KoardSDK

// Configure SDK options
let options = KoardOptions(
    environment: .uat,        // .uat | .production | .custom(String)
    loggingLevel: .debug      // .none | .error | .warning | .debug | .verbose
)

// Initialize with your API key
KoardMerchantSDK.shared.initialize(options: options, apiKey: "your-koard-api-key")

For details on retrieving your key, see Retrieving Your API Key. For authentication and payments, see Running Payments.

Troubleshooting

Common Installation Issues

• Build Errors: Ensure you're using Xcode 16.3 or later
• Runtime Crashes: For a manual XCFramework install, verify the framework is set to "Embed & Sign"
• Import Errors: Check that the package product (or XCFramework) was added to the correct target, and that you import KoardSDK
• Architecture Issues: The XCFramework automatically handles different architectures

Verification Checklist

• Xcode 16.3 or later installed
• iOS 17.0+ deployment target set
• KoardSDK added via Swift Package Manager, or KoardSDK.xcframework added and set to "Embed & Sign"
• Project builds without errors
• import KoardSDK works correctly

Next Steps

Once the SDK is installed and configured:

• Create a Sandbox Apple Account - Ensure your testers are ready
• Configure Tap to Pay - Enable contactless payment functionality
• Implement Payments - Add payment processing to your app
• Understand Payment Lifecycle - Learn about the complete payment flow
• Get Ready for Production - Set up schemes and API keys for launch

See also

This wraps up the SDK installation. See the links below for next steps in your integration:

• Creating a Sandbox Apple Account - Set up dedicated testers
• Adding Tap to Pay - Enable contactless payments
• Running Payments - Implement payment processing
• Payment Lifecycle - Complete payment flow guide
• Apple Best Practices - iOS development guidelines