DocsAPI Reference

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

What you learn

In this guide, you'll learn:

  • How to download the Koard Merchant SDK XCFramework
  • How to add the XCFramework to your Xcode project
  • How to configure embed settings for proper functionality
  • How to verify your installation is working correctly
Prerequisites

Before you begin, ensure you have:

  • Xcode 14.0 or later (required for XCFramework support)
  • iOS 17.0+ deployment target (minimum supported version)
  • iPhone XS or greater (supported hardware for tap-to-pay)
  • Valid Koard merchant account (configured in Koard MMS)
  • Sandbox Apple Account signed in on test device (dedicated iPhone with Developer Mode enabled)

Test Device: Use a dedicated test iPhone with your Sandbox Apple Account signed in. Avoid mixing production Apple IDs on the same hardware to prevent authentication conflicts.

Step 1: Download the SDK

Download the XCFramework

  1. Download the latest KoardMerchantSDK.xcframework.zip from the releases page or get directly from the team
  2. Extract the ZIP file to reveal the KoardMerchantSDK.xcframework bundle

Note: The XCFramework format ensures compatibility across different architectures (iOS Simulator, iOS Device) and simplifies distribution compared to traditional frameworks.

Step 2: Add XCFramework to Your Project

You have two options for adding the XCFramework to your project. We recommend Option A for most use cases.

Option A: Drag and Drop (Recommended)

This is the quickest and most straightforward method:

  1. Open your iOS project in Xcode
  2. In the Project Navigator, right-click on your project root
  3. Select "Add Files to [ProjectName]"
  4. Navigate to the extracted KoardMerchantSDK.xcframework
  5. Select the framework and click "Add"
  6. Ensure "Copy items if needed" is checked and add to your targets

Option B: Manual Addition

If you prefer a more controlled approach:

  1. Select your project in the Project Navigator
  2. Go to your app target's "General" tab
  3. Scroll down to "Frameworks, Libraries, and Embedded Content"
  4. Click the "+" button
  5. Click "Add Other..." → "Add Files..."
  6. Select the KoardMerchantSDK.xcframework and click "Open"

Step 3: Configure Embed Settings

This is crucial for the SDK to work properly in your app.

Configure Framework Embedding

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

Important: If you skip this step, you'll get runtime crashes when trying to use the SDK. The framework must be embedded and signed to function properly.

Step 4: Verify Installation

Check Framework Integration

  1. Build your project (⌘+B) to ensure there are no compilation errors
  2. Verify the framework appears in your project navigator
  3. Check that 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 KoardMerchantSDK

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

Step 5: Initialize the SDK

Basic Configuration

Once the SDK is installed, you can initialize it in your app:

import KoardMerchantSDK

// Initialize the SDK
let koardSDK = KoardMerchantSDK.shared

// Configure with your merchant credentials
koardSDK.configure(
    merchantId: "your-merchant-id",
    apiKey: "your-api-key",
    environment: .sandbox
)

Set Up Error Handling

Implement proper error handling for the SDK:

extension YourViewController: KoardMerchantSDKDelegate {
    func koardSDK(_ sdk: KoardMerchantSDK, didFailWithError error: KoardError) {
        // Handle SDK errors
        print("Koard SDK Error: \(error.localizedDescription)")
    }
  
    func koardSDK(_ sdk: KoardMerchantSDK, didCompletePayment payment: Payment) {
        // Handle successful payment
        print("Payment completed: \(payment.id)")
    }
}

// Set the delegate
koardSDK.delegate = self

Troubleshooting

Common Installation Issues

  • Build Errors: Ensure you're using Xcode 14.0 or later
  • Runtime Crashes: Verify the framework is set to "Embed & Sign"
  • Import Errors: Check that the XCFramework was added to the correct target
  • Architecture Issues: XCFramework automatically handles different architectures

Verification Checklist

  • Xcode 14.0 or later installed
  • iOS 17.0+ deployment target set
  • KoardMerchantSDK.xcframework added to project
  • Framework set to "Embed & Sign"
  • Project builds without errors
  • Import statement works correctly

Next Steps

Once the SDK is installed and configured:

See also

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