跳转到内容

快速接入

阅读此文档前,确保您已完成 集成指南,并了解了 创建收银台的相关 API

PayKKa 提供的 iOS SDK 可以方便您直接以 WebView 的方式嵌入 Web 收银台,只需传给 SDK 一个 sessionId 即可在 App 内打开收银台页面,接收用户的付款,并且可以自定义和处理相关的支付回调。SDK 最新的下载地址可以在 iOS SDK 历史版本和更新日志 中找到。

步骤一:在项目中引入 SDK

SDK 下载后会得到一个 .zip 文件,大致目录结构如下:

.
├── 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 包含两个使用 Objective-C 和 Swift 语言编写的示例 App 的 Xcode 项目工程,开发者可以通过示例代码了解 PayKKa SDK 的 API 使用方式。

解压后位于根目录下的 sdk 文件夹中的 PayKKaCheckoutPayments.xcframework 就是 PayKKa 的基础 SDK。

引入 PayKKa SDK 的方法很简单,在 Xcode 中,依次点击:左侧目录树 <您的项目名称>TARGETS <您的 TARGET>上方 <Build Phases>展开 <Link Binary With Libraries>点击 <条目左下角 + 号>弹窗点击左下角选项 <Add Files…>文件浏览器选择 <sdk/PayKKaCheckoutPayments.xcframework>,即可将 PayKKa SDK 引入项目。

需要注意的是,在:TARGETS <您的 TARGET>上方 <General><Frameworks, Libraries, and Embedded Content> 中,请确保 PayKKaCheckoutPayments.xcframework 设置为 Embed & Sign。如下图所示:

Xcode configuration 1

步骤二:在项目中使用 SDK

SDK 引入之后,就可以开始在您的 App 内集成和使用 PayKKa 的收银台了。以下是使用 SDK 的关键代码,完整代码和示例可以参考随 SDK 下载的 PayKKaCheckoutApp-iOS Xcode 工程项目的源码。

ConfirmOrder.swift
import SwiftUI
/// 引入SDK
import PayKKaCheckoutPayments

struct ConfirmOrder: View {
    @EnvironmentObject var router: NavigationRouter

    /// 定义一个状态值,用于控制WebViewSheet显示/隐藏
    @State private var showWebView = false
    /// PayKKa收银台`sessionId`,一般由后端接口返回,用于构建展示收银台
    private let sessionId: String

    let price: Double = 1118.83;
    var body: some View {
        ScrollView {
            ...
        }
        /// 在此处注册paykkaPaymentWKWebViewSheet组件,可自定义支付回调
        .paykkaPaymentWKWebViewSheet(isPresented: $showWebView, sessionId: sessionId, onPaymentResultCallback: { paymentResult in
            print("---->", paymentResult.toString())
            switch paymentResult.status {
            // 收银台支付成功
            case .success:
                router.redirect(to: .payment_complete(extraData: ["paymentResult": paymentResult]))
            // 收银台会话过期
            case .expired:
                router.redirect(to: .payment_complete(extraData: ["paymentResult": paymentResult]))
                print("onExpired: \(paymentResult.toString())")
            default:
                print("Unhandled payment status: \(paymentResult.status)")
            }
        })
        .navigationTitle("确认订单")
        .navigationBarTitleDisplayMode(.inline)
        HStack {
            Button {
                /// 点击按钮显示WebViewSheet
                showWebView = true
            } label: {
                ...
            }
        }
        ...
    }
    
    init(showWebView: Bool = false, sessionId: String) {
        /// 可在此处初始化PayKKa SDK的运行环境配置等…
        PayKKa.use(.sandbox)
        self.showWebView = showWebView
        self.sessionId = sessionId
    }
}

...

步骤三:测试支付

您可以在 PayKKa 沙盒环境(SANDBOX)中使用测试卡进行支付测试,在打包 App release 版本时再切换到 PROD 环境。

/// SANDBOX(默认)
PayKKa.use(.sandbox)
/// 切换到EU生产环境
PayKKa.use(.prod_EU)
/// 切换到HK生产环境
PayKKa.use(.prod_HK)

注意事项

Apple Pay

1. 如何使用测试卡进行支付测试?

您需要登录 App Store Connect,使用邮箱注册一个沙盒环境的账号,然后在 iOS 设备上登录这个沙盒账号,绑定 Apple Pay 的沙盒环境测试卡后进行支付测试。完整的配置教程可以在 Apple Pay 的官方文档中找到:Apple Pay Sandbox Testing

更多收银台相关文档,请参阅:Payment Method - Apple Pay