# Quick Start

> Before reading this document, make sure you have completed the [Integration Guide](/payments/docs/introduction/integrated-guide) and are familiar with the [APIs for creating a checkout session](/payments/apis/introduction/started).


The PayKKa iOS SDK lets you embed the [Web Checkout](/payments/docs/transaction/web/hosted-web) directly in your app via a WebView. You only need to pass a `sessionId` to open the checkout page inside your app, accept payments from users, and customize or handle related payment callbacks. The latest SDK package is available from [iOS SDK Release History and Changelog](/payments/docs/developer-resources/native-sdks/ios-sdk/release-history).

## Step 1: Add the SDK to Your Project

After downloading the SDK, you will get a `.zip` package with a directory structure similar to the following:

```txt
.
├── PayKKaCheckoutApp-iOS
│   ├── OcCheckoutDemo
│   │   ├── OcCheckoutDemo
│   │   └── OcCheckoutDemo.xcodeproj
│   ├── PayKKaCheckoutApp-iOS.xcworkspace
│   │   ├── contents.xcworkspacedata
│   │   ├── xcshareddata
│   │   └── xcuserdata
│   └── SwiftCheckoutDemo
│       ├── SwiftCheckoutDemo
│       ├── SwiftCheckoutDemo.xcodeproj
│       ├── SwiftCheckoutDemoTests
│       └── SwiftCheckoutDemoUITests
└── sdk
    └── PayKKaCheckoutPayments.xcframework
        ├── Info.plist
        ├── ios-arm64
        └── ios-arm64_x86_64-simulator
```

`PayKKaCheckoutApp-iOS` includes two example Xcode projects written in Objective-C and Swift. You can use these demo apps to understand how to integrate and call the PayKKa SDK APIs.

After extracting the package, the `PayKKaCheckoutPayments.xcframework` file under the root-level `sdk` directory is the core PayKKa SDK.

Adding the PayKKa SDK is straightforward. In Xcode, click in order: `<Your Project>` in the left file tree → `TARGETS <Your Target>` → `Build Phases` → expand `Link Binary With Libraries` → click the `+` button at the lower-left corner → choose `Add Files...` in the popup → then select `sdk/PayKKaCheckoutPayments.xcframework` in the file picker.

Also note that under `TARGETS <Your Target>` → `General` → `Frameworks, Libraries, and Embedded Content`, make sure `PayKKaCheckoutPayments.xcframework` is set to `Embed & Sign`, as shown below:

Xcode configuration 1
## Step 2: Obtain the AppCode

During initialization, the SDK verifies whether the host app's `Bundle Identifier`, signing `Team ID`, and other metadata match the information registered in the PayKKa database. This ensures that SDK calls come from the merchant's official app distribution channel. Therefore, you need to provide the following app information:

- App `Bundle Identifier`
- The signing developer account `Team ID`


You can find the app bundle identifier in your project code or in Xcode at `TARGETS <Your Target>` → `Signing & Capabilities` → `Signing` → `Bundle Identifier`.

The Team ID of the Apple Developer account used to sign the app can be found in the [Account - Apple Developer](https://developer.apple.com/account).

Please provide your app’s bundle identifier and the Team ID of your Apple Developer account to our integration team. We will generate a `PayKKaAppCode` for you.

Then, in your app project’s `Info.plist`, add the following metadata entries:

- A metadata entry named `paykka_appcode`, whose value should be the `PayKKaAppCode` we generated for you
- A metadata entry named `paykka_mch_teamid`, whose value should be your Apple Developer account’s `Team ID`


## Step 3: Use the SDK in Your Project

Once the SDK has been added, you can start integrating and using the PayKKa checkout in your app. The following sections show the key integration code. For complete examples, refer to the source code of the `PayKKaCheckoutApp-iOS` Xcode project included with the SDK package.

Swift
```swift AppConf.swift
import Foundation
import PayKKaCheckoutPayments

struct AppConf {
    /// Define your configuration
    static let CONFIGURATION: PayKKaConf = {
        PayKKaConf(dict: [
            /// Your PayKKa gateway merchant ID
            KEY_GATEWAY_MERCHANT_ID: "{YOUR_GATEWAY_MERCHANT_ID}",
            /// Your client key
            KEY_CLIENT_KEY: "{YOUR_CLIENT_KEY}",
        ])
    }()
}
```

```swift ConfirmOrder.swift
import SwiftUI
/// Import the SDK
import PayKKaCheckoutPayments

struct ConfirmOrder: View {
    @EnvironmentObject var router: NavigationRouter

    /// The PayKKa checkout `sessionId`, usually returned by your backend API and used to open the checkout
    private let sessionId: String

    let price: Double = 1118.83;
    var body: some View {
        ScrollView {
            ...
        }
        .navigationTitle("Confirm Order")
        .navigationBarTitleDisplayMode(.inline)
        HStack {
            Button {
                /// Open the payment sheet here and customize the payment callbacks if needed
                PayKKa.goPay(sessionId) { paymentResult in
                    print("---->", paymentResult.toString())
                    switch paymentResult.status {
                    case .success:
                        // Checkout payment succeeded
                        router.redirect(to: .payment_complete(extraData: ["paymentResult": paymentResult]))
                    case .expired:
                        // Checkout session expired
                        router.redirect(to: .payment_complete(extraData: ["paymentResult": paymentResult]))
                        print("onExpired: \(paymentResult.toString())")
                    default:
                        print("Unhandled payment status: \(paymentResult.status)")
                    }
                } onCloseTappedCallback: { jsEvent in
                    print("On close tapped.")
                }
            } label: {
                ...
            }
        }
        ...
    }
    
    init(sessionId: String) {
        /// Initialize the PayKKa SDK
        PayKKa.Init(AppConf.CONFIGURATION, AppConf.ENVIRONMENT)
        self.sessionId = sessionId
    }
}

...
```

Objective-C
```objective-c AppConf.m
#import "AppConf.h"

NS_ASSUME_NONNULL_BEGIN

@implementation AppConf

/// Define your configuration
+ (PayKKaConf *)CONFIGURATION {
    static PayKKaConf *conf;
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        conf = [[PayKKaConf alloc] initWithDict:@{
            /// Your PayKKa gateway merchant ID
            KEY_GATEWAY_MERCHANT_ID: @"{YOUR_GATEWAY_MERCHANT_ID}",
            /// Your client key
            KEY_CLIENT_KEY: @"{YOUR_CLIENT_KEY}",
        }];
    });
    return conf;
}

@end

NS_ASSUME_NONNULL_END
```

```objective-c ConfirmOrderViewController.m
#import "ConfirmOrderViewController.h"
#import "../PaymentComplete/PaymentCompleteViewController.h"
/// Import the SDK header
#import <PayKKaCheckoutPayments/PayKKaCheckoutPayments.h>

NS_ASSUME_NONNULL_BEGIN

...

@implementation ConfirmOrderViewController

- (instancetype)initWithExtraData:(NSDictionary *)extra {
    self = [super init];
    if (self) {
        _sessionId = extra[@"sessionId"] ?: @"";
        _price = 1118.83;
        
        /// Initialize the PayKKa SDK
        [PayKKa init:AppConf.CONFIGURATION environment:AppConf.ENVIRONMENT];
        // [PayKKa init:AppConf.CONFIGURATION];
    }
    return self;
}

- (void)viewDidLoad {
    [super viewDidLoad];
    self.title = @"Confirm Order";
    self.view.backgroundColor = [UIColor systemGray6Color];

    [self buildScrollView];
    [self buildOrderCard];
    [self buildBottomPayButton];
}

- (void)buildScrollView {
    ...
}

- (void)buildOrderCard {
    ...
}

- (void)buildBottomPayButton {
    ...
}

- (void)openCheckout {
    /// Show the WebView sheet
    UINavigationController *nav = self.navigationController;
    UIViewController *presentingVC = nav.topViewController;
    /// Call this method directly to present the WKWebView sheet and customize the payment callback
    [PayKKa goPay: AppConf.EXAMPLE_CHECKOUT_SESSION_ID onPaymentCallback:^(PaymentResult * _Nonnull paymentResult) {
        PaymentCompleteViewController *vc = [[PaymentCompleteViewController alloc] initWithPaymentResult:paymentResult];
        switch (paymentResult.status) {
            // Checkout payment succeeded
            case PaymentStatusSuccess: {
                NSArray *newStack = @[nav.viewControllers.firstObject, vc];
                [nav setViewControllers:newStack animated:YES];
                break;
            }
            // Checkout session expired
            case PaymentStatusExpired: {
                NSArray *newStack = @[nav.viewControllers.firstObject, vc];
                [nav setViewControllers:newStack animated:YES];
                NSLog(@"onExpired: %@", [paymentResult toString]);
                break;
            }
            default:
                NSLog(@"Unhandled payment status: %@", @(paymentResult.status));
                break;
        }
    }];
}

@end

NS_ASSUME_NONNULL_END
```

## Step 4: Test Payments

You can use test cards in the PayKKa sandbox environment (`SANDBOX`) for payment testing, and switch to a production environment when building the release version of your app.

Swift
```swift
// You can specify the payment environment in the init method
PayKKa.Init(AppConf.CONFIGURATION, AppConf.ENVIRONMENT)

/// SANDBOX (default)
PayKKa.useEnv(.SANDBOX)
/// Switch to the EU production environment
PayKKa.useEnv(.PROD_EU)
/// Switch to the HK production environment
PayKKa.useEnv(.PROD_HK)
```

Objective-C
```objective-c
// You can specify the payment environment in the init method
[PayKKa init:AppConf.CONFIGURATION environment:AppConf.ENVIRONMENT];

/// SANDBOX (default)
[PayKKa useEnv:PayKKaEnv.SANDBOX];
/// Switch to the EU production environment
[PayKKa useEnv:PayKKaEnv.PROD_EU];
/// Switch to the HK production environment
[PayKKa useEnv:PayKKaEnv.PROD_HK];
```

## Notes

### Apple Pay

#### 1. How do I use test cards for payment testing?

You need to sign in to App Store Connect, create a sandbox account with an email address, then sign in to that sandbox account on your iOS device. After adding Apple Pay sandbox test cards, you can perform payment testing. A full setup guide is available in the official Apple documentation: [Apple Pay Sandbox Testing](https://developer.apple.com/apple-pay/sandbox-testing/).

For more checkout-related documentation, see: [Payment Method - Apple Pay](/payments/docs/payment-method/apple-pay/apple-pay#testing)