# SDK API Reference

## PayKKa

The main entry point for the SDK, used for environment configuration and initiating the payment process.

### useEnv()

Switch the environment configuration used by the SDK.

- **Type**

```objectivec
+ (void)useEnv:(PayKKaEnv *)env;
```
- **Details**
Before calling the payment API, you can set the SDK's operating environment using this method. The SDK defaults to the production environment. It is generally recommended to configure this at app startup (e.g., in `AppDelegate`).
- **Example**

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

// Set to sandbox environment
[PayKKa useEnv:PayKKaEnv.SANDBOX];
```
- **Reference** [PayKKaEnv](#paykkaenv)


### goPay()

Initiate the payment process and display the checkout page.

- **Type**

```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;
```
- **Details**
This method creates a full-screen checkout view controller and presents it on top of the provided view controller. It supports handling payment result callbacks and optional close button tap events.
  - `from`: The view controller currently being displayed.
  - `sessionId`: The payment Session ID retrieved from the backend.
  - `onPaymentCallback`: Callback after payment completion, returning a `PaymentResult` object.
  - `onCloseTappedCallback`: Optional. Triggered when the user taps the close button in the top-left corner of the checkout.
- **Example**

```objectivec
[PayKKa goPay:self 
    sessionId:@"your_session_id"
onPaymentCallback:^(PaymentResult *result) {
    if (result.status == PaymentStatusSuccess) {
        NSLog(@"Payment successful");
    } else {
        NSLog(@"Payment failed: %@", result.message);
    }
  }];
```


# SwiftUI API

## PayKKaPaymentWKWebView

A checkout component for SwiftUI that wraps the native `WKWebView`.

### Constructor

Initialize the checkout WebView component.

- **Type**

```swift
public init(
    sessionId: String,
    isPresented: Binding<Bool>,
    onPaymentCallback: ((PaymentResult) -> Void)?,
    onCloseTappedCallback: ((JSEvent) -> Void)? = nil
)
```
- **Details**
This component automatically generates the corresponding payment URL based on `PayKKa.currentEnv`. When the payment is complete or the user manually closes the checkout, the component sets `isPresented` to `false` to dismiss the view.
  - `sessionId`: The Session ID created in the PayKKa backend.
  - `isPresented`: A binding value to control the presentation state of the checkout.
  - `onPaymentCallback`: Callback after payment completion.
  - `onCloseTappedCallback`: Callback when the user taps the close button.
- **Example**

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


## View Extension

Convenient extension methods provided by PayKKa for SwiftUI `View`.

### paykkaPaymentWKWebViewSheet()

Quickly present the payment checkout as a sheet.

- **Type**

```swift
func paykkaPaymentWKWebViewSheet(
    isPresented: Binding<Bool>,
    sessionId: String,
    onPaymentResultCallback: ((PaymentResult) -> Void)?,
    onCloseTappedCallback: ((JSEvent) -> Void)? = nil
) -> some View
```
- **Details**
This is a convenient wrapper around `.sheet` and `PayKKaPaymentWKWebView`, with interactive dismiss disabled by default (`interactiveDismissDisabled(true)`) to ensure the integrity of the payment process.
- **Example**

```swift
ContentView()
    .paykkaPaymentWKWebViewSheet(
        isPresented: $isPresented,
        sessionId: sessionId,
        onPaymentResultCallback: { result in
            // Process result
        }
    )
```


# Environment Configuration API

## PayKKaEnv

Defines the backend environments the SDK connects to.

- **Preset Environments**
  - `PayKKaEnv.SANDBOX`: Sandbox test environment.
  - `PayKKaEnv.PROD_EU`: European production environment.
  - `PayKKaEnv.PROD_HK`: Hong Kong production environment.


### initWithFormat()

Initialize the environment with a custom URL format (typically used for internal debugging).

- **Type**

```objectivec
- (instancetype)initWithFormat:(NSString *)format;
```
- **Details**
If you need to connect to a custom test server, you can use this method. The URL format should include the `{sessionId}` placeholder.


# Data Models

## PaymentResult

An object containing detailed information about the payment result.

- **Properties**
  - `status` (`PaymentStatus`): Payment status.
  - `message` (`NSString *`): Relevant tips or error messages.
  - `result` (`NSDictionary *`): Raw payment data.


### PaymentStatus

Payment status enum:

- `PaymentStatusSuccess`: Payment successful.
- `PaymentStatusExpired`: Payment session expired.
- `PaymentStatusError`: An error occurred during payment.
- `PaymentStatusUnknown`: Unknown status.


### toString()

Serialize the payment result into a JSON string.

- **Type**

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