# SDK接口文档

## PayKKa

SDK 的主入口类，用于配置环境和发起支付流程。

### useEnv()

切换 SDK 使用的环境配置。

- **类型**

```objectivec
+ (void)useEnv:(PayKKaEnv *)env;
```
- **详细信息**
在调用支付接口之前，你可以通过此方法设置 SDK 的运行环境。SDK 默认使用生产环境。通常建议在应用启动时（如 `AppDelegate` 中）进行配置。
- **示例**

```objectivec
#import <PayKKaCheckoutPayments/PayKKa.h>

// 设置为沙箱环境
[PayKKa useEnv:PayKKaEnv.SANDBOX];
```
- **参考** [PayKKaEnv](#paykkaenv)


### goPay()

发起支付流程，展示收银台页面。

- **类型**

```objectivec
+ (void)goPay:(UIViewController *)from 
    sessionId:(NSString *)sessionId
onPaymentCallback:(PayKKaCallback)onPaymentCallback;

+ (void)goPay:(UIViewController *)from 
    sessionId:(NSString *)sessionId
onPaymentCallback:(PayKKaCallback)onPaymentCallback
onCloseTappedCallback:(void (^ _Nullable)(JSEvent *jsEvent))onCloseTappedCallback;
```
- **详细信息**
该方法会创建一个全屏的收银台视图控制器，并将其展示在提供的视图控制器之上。它支持处理支付结果回调以及可选的关闭按钮点击事件。
  - `from`: 当前展示的视图控制器。
  - `sessionId`: 从后端获取的支付 Session ID。
  - `onPaymentCallback`: 支付完成后的回调，返回 `PaymentResult` 对象。
  - `onCloseTappedCallback`: 可选。当用户点击收银台左上角的关闭按钮时触发。
- **示例**

```objectivec
[PayKKa goPay:self 
    sessionId:@"your_session_id"
onPaymentCallback:^(PaymentResult *result) {
    if (result.status == PaymentStatusSuccess) {
        NSLog(@"支付成功");
    } else {
        NSLog(@"支付失败: %@", result.message);
    }
  }];
```


# SwiftUI API

## PayKKaPaymentWKWebView

一个用于 SwiftUI 的收银台组件，封装了原生的 `WKWebView`。

### 构造函数

初始化收银台 WebView 组件。

- **类型**

```swift
public init(
    sessionId: String,
    isPresented: Binding<Bool>,
    onPaymentCallback: ((PaymentResult) -> Void)?,
    onCloseTappedCallback: ((JSEvent) -> Void)? = nil
)
```
- **详细信息**
该组件会自动根据 `PayKKa.currentEnv` 生成对应的支付 URL。当支付完成或用户主动关闭收银台时，组件会自动将 `isPresented` 设置为 `false` 以关闭视图。
  - `sessionId`: PayKKa 后台创建的 Session ID。
  - `isPresented`: 绑定值，用于控制收银台的展示状态。
  - `onPaymentCallback`: 支付完成后的回调。
  - `onCloseTappedCallback`: 用户点击关闭按钮时的回调。
- **示例**

```swift
struct CheckoutView: View {
    @State private var showPayment = false
    
    var body: some View {
        Button("去支付") {
            showPayment = true
        }
        .sheet(isPresented: $showPayment) {
            PayKKaPaymentWKWebView(
                sessionId: "session_123",
                isPresented: $showPayment,
                onPaymentCallback: { result in
                    print("支付结果: \(result.status)")
                }
            )
        }
    }
}
```


## View 扩展

PayKKa 为 SwiftUI `View` 提供的便捷扩展方法。

### paykkaPaymentWKWebViewSheet()

以 Sheet 形式快捷弹出支付收银台。

- **类型**

```swift
func paykkaPaymentWKWebViewSheet(
    isPresented: Binding<Bool>,
    sessionId: String,
    onPaymentResultCallback: ((PaymentResult) -> Void)?,
    onCloseTappedCallback: ((JSEvent) -> Void)? = nil
) -> some View
```
- **详细信息**
这是对 `.sheet` 和 `PayKKaPaymentWKWebView` 的快捷封装，并默认禁用了交互式关闭（`interactiveDismissDisabled(true)`），以确保支付流程的完整性。
- **示例**

```swift
ContentView()
    .paykkaPaymentWKWebViewSheet(
        isPresented: $isPresented,
        sessionId: sessionId,
        onPaymentResultCallback: { result in
            // 处理结果
        }
    )
```


# 环境配置 API

## PayKKaEnv

用于定义 SDK 连接的后端环境。

- **预置环境**
  - `PayKKaEnv.SANDBOX`: 沙箱测试环境。
  - `PayKKaEnv.PROD_EU`: 欧洲生产环境。
  - `PayKKaEnv.PROD_HK`: 香港生产环境。


### initWithFormat()

使用自定义的 URL 格式初始化环境（通常用于内部调试）。

- **类型**

```objectivec
- (instancetype)initWithFormat:(NSString *)format;
```
- **详细信息**
如果你需要连接到自定义的测试服务器，可以使用此方法。URL 格式中应包含 `{sessionId}` 占位符。


# 数据模型

## PaymentResult

包含支付结果详细信息的对象。

- **属性**
  - `status` (`PaymentStatus`): 支付状态。
  - `message` (`NSString *`): 相关的提示或错误信息。
  - `result` (`NSDictionary *`): 原始支付数据。


### PaymentStatus

支付状态枚举：

- `PaymentStatusSuccess`: 支付成功。
- `PaymentStatusExpired`: 支付会话已过期。
- `PaymentStatusError`: 支付过程中发生错误。
- `PaymentStatusUnknown`: 未知状态。


### toString()

将支付结果序列化为 JSON 字符串。

- **类型**

```objectivec
- (NSString *)toString;
```