The SDK's main entry-point class, used to configure the environment, initialize the SDK flow, and more.

Switches the environment and merchant configurations currently used by the SDK.

• Type

  + (void)useEnv:(PayKKaEnv *)env;
  + (void)useConf:(PayKKaConf *)conf;

  PayKKa.useEnv(_ env: PayKKaEnv)
  PayKKa.useConf(_ conf: PayKKaConf)

• Details

  • useEnv: Switches the runtime environment currently used by the SDK.
  • useConf: Switches the merchant configuration currently used by the SDK.
  • These two methods only update the current global configuration; they do not automatically run the complete initialization flow.
  • The SDK's default environment is PayKKaEnv.SANDBOX.
  • In general, initialize the SDK once during app startup rather than switching configurations each time a payment is initiated.

• Example

  #import <PayKKaCheckoutPayments/PayKKa.h>
  
  [PayKKa useEnv:PayKKaEnv.SANDBOX];
  [PayKKa useConf:appConf];

  PayKKa.useEnv(.SANDBOX)
  PayKKa.useConf(appConf)

• See also

  • PayKKaEnv
  • PayKKaConf

Initializes the SDK and applies the environment and merchant configurations.

• Type

  + (void)init:(PayKKaConf *)configuration environment:(nullable PayKKaEnv *)environment;
  + (void)init:(PayKKaConf *)configuration;

  PayKKa.Init(_ configuration: PayKKaConf, _ environment: PayKKaEnv?)
  PayKKa.Init(_ configuration: PayKKaConf)

• Details

  • configuration: The merchant configuration object. It must contain at least the gateway merchant ID and client key.
  • environment: An optional runtime environment. If it is nil, PayKKaEnv.SANDBOX is used by default.
  • Internally, init calls useEnv(...) and useConf(...) and completes SDK initialization.
  • Initialization must be completed before creating PKPaymentBottomSheet or any PKPaymentBase subclass, or before calling goPay(...); otherwise, the SDK throws NSInternalInconsistencyException.
  • The Swift API is exposed as PayKKa.Init(...), with an uppercase I.

• Example

  [PayKKa init:appConf environment:PayKKaEnv.SANDBOX];
  // Or use the default SANDBOX environment
  [PayKKa init:appConf];

  PayKKa.Init(appConf, .SANDBOX)
  // Or use the default SANDBOX environment
  PayKKa.Init(appConf)

The built-in implementation of PayKKaEnvironment, used to define the backend environment to which the SDK connects.

• Type

  @interface PayKKaEnv : PayKKaEnvironment

• Preset environments

  • PayKKaEnv.SANDBOX: Sandbox testing environment.
  • PayKKaEnv.PROD_EU: European production environment.
  • PayKKaEnv.PROD_HK: Hong Kong production environment.

• Details

  • Preset environments are provided through class properties, not an Objective-C enumeration.
  • Use environmentCode to obtain the current environment code.

Defines the merchant and payment method configurations used by the SDK.

• Type

  @interface PayKKaConf : NSObject

• Properties

  • configuration (NSDictionary *): The raw dictionary of the current configuration object.

• Configuration options

  • KEY_GATEWAY_MERCHANT_ID: Gateway merchant ID.
  • KEY_CLIENT_KEY: Checkout Client Key.
  • KEY_LOCALE: The language and region used by the SDK.
  • KEY_APPLE_PAY_MERCHANT_ID: Apple Pay Merchant ID.
  • KEY_ALIPAY_PLUS_ACQUIRER_ID: Alipay+ Acquirer ID.
  • KEY_WECHAT_PAY_APP_ID: WeChat Open Platform App ID.
  • KEY_WECHAT_PAY_APP_UNIVERSAL_LINK: Your app's Universal Link, used to return users to the app after payment is completed.

Initializes a merchant configuration object with a dictionary.

• Type

  - (instancetype)initWithDict:(NSDictionary *)dict;

  PayKKaConf(dict: [AnyHashable: Any])

• Details

  • At least KEY_GATEWAY_MERCHANT_ID and KEY_CLIENT_KEY must be provided.
  • When integrating Apple Pay, Alipay+, or WeChat Pay, also provide the corresponding payment method configuration options.

• Example

  PayKKaConf *appConf = [[PayKKaConf alloc] initWithDict:@{
      KEY_GATEWAY_MERCHANT_ID: @"your_gateway_merchant_id",
      KEY_CLIENT_KEY: @"your_client_key",
      KEY_APPLE_PAY_MERCHANT_ID: @"merchant.com.example",
      KEY_ALIPAY_PLUS_ACQUIRER_ID: @"your_acquirer_id",
      KEY_WECHAT_PAY_APP_ID: @"your_wechat_app_id",
      KEY_WECHAT_PAY_APP_UNIVERSAL_LINK: @"https://example.com/wechat/"
  }];

  let appConf = PayKKaConf(dict: [
      KEY_GATEWAY_MERCHANT_ID: "your_gateway_merchant_id",
      KEY_CLIENT_KEY: "your_client_key",
      KEY_APPLE_PAY_MERCHANT_ID: "merchant.com.example",
      KEY_ALIPAY_PLUS_ACQUIRER_ID: "your_acquirer_id",
      KEY_WECHAT_PAY_APP_ID: "your_wechat_app_id",
      KEY_WECHAT_PAY_APP_UNIVERSAL_LINK: "https://example.com/wechat/"
  ])

The base class for each payment method. It stores the Checkout Session, payment result callback, and payment request interceptor.

• Type

  @interface PKPaymentBase : NSObject

• Properties

  • paymentResultCallback (id<PKPaymentResultCallback>, nullable): The payment result callback.
  • interceptor (id<PKPaymentInterceptor>, nullable): The interceptor invoked before the payment request is presented.

• Methods

  • initWithCheckoutSessionId:: Creates a payment object using a Checkout Session ID.
  • setError:: Updates or clears the error displayed by the associated payment form.
  • notifyResult:: Sends a terminal payment status to the result callback.
  • notifyError:: Sends a payment error to the result callback.
  • notifyUserCanceled:extraData:: Sends a user cancellation event to the result callback.

• Details

  • The default initializer is unavailable. Use the designated initializer provided by the specific payment class.
  • PayKKa must be initialized before creating a payment object.
  • paymentResultCallback must be set before initiating payment.
  • Both paymentResultCallback and interceptor are strong references. Set them to nil when the page is destroyed or the payment object is no longer used to avoid retain cycles.

The unified callback protocol for receiving payment results, errors, and user cancellation events.

• Type

  @protocol PKPaymentResultCallback <NSObject>

• Methods

  - (void)onResult:(PKPaymentResult *)paymentResult;
  - (void)onError:(id)throwable;
  - (void)onUserCanceled:(nullable PKPaymentBase *)paymentSource
               extraData:(nullable NSDictionary *)extraData;

  func onResult(_ paymentResult: PKPaymentResult)
  func onError(_ throwable: Any)
  func onUserCanceled(
      _ paymentSource: PKPaymentBase?,
      extraData: [AnyHashable: Any]?
  )

• Details

  • onResult:: Required method that receives the normalized terminal payment result.
  • onError:: Optional method that receives a payment error. Its parameter type is id and may be an NSError or another error object.
  • onUserCanceled:extraData:: Optional method called when the user cancels the payment.
  • After an error or cancellation, the merchant app should generally stop displaying its loading state and allow the user to try paying again.

An optional interceptor protocol invoked before the payment request is presented.

• Type

  @protocol PKPaymentInterceptor <NSObject>

• Methods

  - (void)beforeRequestPayment:(id)paymentSource;

  func beforeRequestPayment(_ paymentSource: Any)

• Details

  • It is currently used primarily by Apple Pay before the system payment sheet is presented.
  • In this method, you can read PKApplePayment.paymentRequest and adjust request content such as the payment summary.

A bottom sheet that displays the native Drop-In checkout containing multiple payment methods.

• Type

  @interface PKPaymentBottomSheet : NSObject

• Properties

  • onPayCallback (id<PKPaymentResultCallback>): The payment result callback, which must be set before presentation.
  • isUiInitCompleted (BOOL): Indicates whether checkout UI initialization is complete.
  • isProcessing (BOOL): Indicates whether the checkout is currently processing a payment.

Creates a Drop-In checkout using a Checkout Session ID.

• Type

  - (instancetype)initWithCheckoutSessionId:(nullable NSString *)checkoutSessionId;
  
  - (instancetype)initWithCheckoutSessionId:(nullable NSString *)checkoutSessionId
                        onSheetCloseCallback:(void (^ _Nullable)(PKPaymentBottomSheet *sheet))onSheetCloseCallback;

  PKPaymentBottomSheet(checkoutSessionId: String?)
  PKPaymentBottomSheet(
      checkoutSessionId: String?,
      onSheetCloseCallback: ((PKPaymentBottomSheet) -> Void)?
  )

• Details

  • checkoutSessionId: A valid Checkout Session ID created by the server.
  • onSheetCloseCallback: Called on the main thread after the sheet's closing animation completes.
  • The default initializer is unavailable.

Configures and presents the Drop-In checkout.

• Type

  - (void)showMerchantName;
  - (void)showFromPresenter:(nullable UIViewController *)presenter
                 completion:(void (^ _Nullable)(void))completion;

  sheet.showMerchantName()
  sheet.show(fromPresenter: UIViewController?, completion: (() -> Void)?)

• Details

  • showMerchantName: Displays the merchant name section, which is hidden by default.
  • presenter: The view controller used for modal presentation. When nil is passed, the SDK automatically finds the current view controller suitable for presentation.
  • completion: The callback invoked after the presentation animation completes.

Closes the Drop-In checkout.

• Type

  - (void)hideWithCompletion:(void (^ _Nullable)(void))completion;
  - (void)hide;

• Details

  • When leaving the page or no longer using the sheet, call hide and release the instance.
  • Use setShouldDismissOnBackgroundTap: and setShouldDismissOnDraggingDownSheet: to control user dismissal behavior.

• Example

  PKPaymentBottomSheet *sheet =
      [[PKPaymentBottomSheet alloc]
          initWithCheckoutSessionId:@"your_session_id"
          onSheetCloseCallback:^(PKPaymentBottomSheet *sheet) {
              NSLog(@"Checkout closed");
          }];
  sheet.onPayCallback = self;
  [sheet showMerchantName];
  [sheet showFromPresenter:self completion:nil];

  let sheet = PKPaymentBottomSheet(checkoutSessionId: "your_session_id") { _ in
      print("Checkout closed")
  }
  sheet.onPayCallback = callback
  sheet.showMerchantName()
  sheet.show(fromPresenter: nil, completion: nil)

Builds an Apple Pay request, presents the system payment sheet, and submits payment credentials.

• Type

  @interface PKApplePayment : PKPaymentBase

• Properties

  • form (PKApplePaymentForm *, nullable): The associated Apple Pay form.
  • paymentRequest (PKPaymentRequest *, nullable): The Apple Pay request generated for the current payment flow.
  • paymentResultCallback: The payment result callback inherited from PKPaymentBase.
  • interceptor: The payment request interceptor inherited from PKPaymentBase.

Initiates an Apple Pay payment.

• Type

  - (void)requestPaymentWithCheckoutSessionId:(nullable NSString *)checkoutSessionId;
  - (void)requestPayment;
  + (BOOL)canMakePayments;

  payment.request()
  PKApplePayment.canMakePayments()

• Details

  • requestPaymentWithCheckoutSessionId:: Initiates payment using the provided Checkout Session ID.
  • requestPayment: Initiates payment using the Checkout Session ID stored during initialization.
  • canMakePayments: Checks whether the device has basic Apple Pay capability. It does not validate the merchant, card network, or currency configuration for the current Checkout.
  • paymentResultCallback must be set before this method is called.
  • Use setError:nil to clear an old error from the associated form.

• Example

  PKApplePayment *payment =
      [[PKApplePayment alloc] initWithCheckoutSessionId:@"your_session_id"];
  payment.form = form;
  payment.paymentResultCallback = self;
  payment.interceptor = self;
  [payment setError:nil];
  [payment requestPayment];

  let payment = PKApplePayment(checkoutSessionId: "your_session_id")
  payment.form = form
  payment.paymentResultCallback = callback
  payment.interceptor = interceptor
  payment.setError(nil)
  payment.request()

An Apple Pay form component containing the Apple Pay button, loading state, and error message area.

• Type

  @interface PKApplePaymentForm : UIControl

• Properties

  • pkApplePaymentButton (PKApplePaymentButton *): The Apple Pay payment button.

• Methods

  • setError:: Updates or clears the payment error.
  • setLoading:animated:: Updates the form's loading state.

The Apple Pay payment button component.

• Type

  @interface PKApplePaymentButton : UIControl

• Properties

  • applePaymentButton (PKPaymentButton *): The internal PassKit button.
  • onTap: The button tap callback.
  • loading (BOOL): Indicates whether the button is currently loading.

• Methods

  • setEnabled:animated:: Updates whether the button is enabled.
  • setLoading:: Updates the loading state.
  • setLoading:animated:: Updates the loading state with an animation.

• Details

  • Bind business tap events to the outer PKApplePaymentButton, not directly to the internal PKPaymentButton.
  • If both onTap and Target/Action are set, the SDK runs onTap first and then sends UIControlEventTouchUpInside.

Initializes the card form configuration, validates the form, and submits a card payment.

• Type

  @interface PKBankCardPayment : PKPaymentBase

• Properties

  • form (PKCardPaymentForm *): The card form bound to the current payment object.

Creates a payment object using a card form and Checkout Session ID.

• Type

  - (instancetype)initWithPKCardPaymentForm:(nullable PKCardPaymentForm *)form
                          checkoutSessionId:(nullable NSString *)checkoutSessionId;
  
  - (instancetype)initWithPKCardPaymentForm:(nullable PKCardPaymentForm *)form
                          checkoutSessionId:(nullable NSString *)checkoutSessionId
                                   complete:(void (^ _Nullable)(NSError * _Nullable error,
                                                                NSDictionary * _Nullable sessionInfo))complete;

  PKBankCardPayment(
      pkCardPaymentForm: PKCardPaymentForm?,
      checkoutSessionId: String?,
      complete: ((Error?, [AnyHashable: Any]?) -> Void)?
  )

• Details

  • form: The form used to collect card and billing address information. It must be available when payment is initiated.
  • checkoutSessionId: The Checkout Session ID created by the server.
  • complete: The callback invoked after the asynchronous field configuration request completes. It returns Session information on success or an error on failure.
  • complete is called only when the form field configuration must be loaded asynchronously. It is not called if the form is nil or field configuration has already completed.
  • The base class's initWithCheckoutSessionId: is unavailable for PKBankCardPayment.

Validates the form and initiates a card payment.

• Type

  - (void)requestPaymentWithCheckoutSessionId:(nullable NSString *)checkoutSessionId;

• Details

  • Before initiating payment, set paymentResultCallback and ensure that form initialization is complete and the input is valid.
  • Disable the form and payment button until form initialization is complete.
  • Use setError:nil to clear an old payment error from the form.

• Example

  PKCardPaymentForm *form = [[PKCardPaymentForm alloc] init];
  PKBankCardPayment *payment =
      [[PKBankCardPayment alloc]
          initWithPKCardPaymentForm:form
          checkoutSessionId:@"your_session_id"
          complete:^(NSError *error, NSDictionary *sessionInfo) {
              if (error) {
                  [form setError:error];
              }
          }];
  payment.paymentResultCallback = self;
  [payment requestPaymentWithCheckoutSessionId:@"your_session_id"];

A form component that collects and validates card, cardholder, and billing address information.

• Type

  @interface PKCardPaymentForm : UIControl

• Methods

  - (void)validateWithCallback:(void (^)(NSArray<NSNumber *> *resultArray))onValidateCallback
               onErrorCallback:(void (^)(NSError *error))onErrorCallback;
  
  - (void)setEditingChangedCallback:(void (^)(void))onAllFieldsValidCallback
        onFieldInputInvalidCallback:(void (^)(NSError *error))onFieldInputInvalidCallback;
  
  - (void)setError:(nullable id)throwable;

• Details

  • validateWithCallback:onErrorCallback:: Validates all payment fields and synchronously updates their error styles.
  • setEditingChangedCallback:onFieldInputInvalidCallback:: Observes real-time form validation state and can be used to control whether the payment button is enabled.
  • setError:: Updates or clears the payment error at the bottom of the form without changing the validation state of individual input fields.
  • Set the editing callback only once. Repeated calls may add additional listeners to the input fields.

Creates an Alipay+ payment order, presents the payment sheet, and handles the payment result.

• Type

  @interface PKAlipayPlusPayment : PKPaymentBase

• Properties

  • form (PKAlipayPlusPaymentForm *, nullable): The Alipay+ form used to display payment errors.

Initiates an Alipay+ payment.

• Type

  - (void)requestPaymentWithCheckoutSessionId:(nullable NSString *)checkoutSessionId;
  - (void)requestPayment;

  payment.request()

• Details

  • paymentResultCallback must be set before this method is called.
  • requestPayment uses the Checkout Session ID stored during initialization.
  • It depends on KEY_ALIPAY_PLUS_ACQUIRER_ID in the merchant configuration.
  • After the user returns to the app from an external wallet or page, the SDK may continue polling for the order's final status and complete the result callback.

• Example

  let form = PKAlipayPlusPaymentForm()
  let payment = PKAlipayPlusPayment(checkoutSessionId: "your_session_id")
  payment.form = form
  payment.paymentResultCallback = callback
  payment.setError(nil)
  payment.request()

A form component used to display Alipay+ payment errors.

• Type

  @interface PKAlipayPlusPaymentForm : UIControl

• Methods

  • setError:: Updates or clears the payment error.

• Details

  • It currently has no additional input fields and is used primarily to present the error state.
  • The merchant app provides the payment button separately.

Creates a WeChat Pay order, opens the WeChat app, and handles the payment result.

• Type

  @interface PKWeChatPayment : PKPaymentBase

• Properties

  • form (PKWeChatPaymentForm *, nullable): The WeChat Pay form used to display payment errors.

Initiates a WeChat Pay payment.

• Type

  - (void)requestPaymentWithCheckoutSessionId:(nullable NSString *)checkoutSessionId;
  - (void)requestPayment;

  payment.request()

• Details

  • paymentResultCallback must be set before this method is called.
  • requestPayment uses the Checkout Session ID stored during initialization.
  • It depends on KEY_WECHAT_PAY_APP_ID and KEY_WECHAT_PAY_APP_UNIVERSAL_LINK in the merchant configuration.
  • After the user returns to the app from WeChat, the SDK may continue polling for the order's final status and complete the result callback.

• Example

  PKWeChatPaymentForm *form = [[PKWeChatPaymentForm alloc] init];
  PKWeChatPayment *payment =
      [[PKWeChatPayment alloc] initWithCheckoutSessionId:@"your_session_id"];
  payment.form = form;
  payment.paymentResultCallback = self;
  [payment setError:nil];
  [payment requestPayment];

A form component used to display WeChat Pay payment errors.

• Type

  @interface PKWeChatPaymentForm : UIControl

• Methods

  • setError:: Updates or clears the payment error.

• Details

  • It currently has no additional input fields and is used primarily to present the error state.
  • The merchant app provides the payment button separately.

Forwards URL Scheme and Universal Link callbacks received by the merchant app to WeChatOpenSDK and the current WeChat Pay object.

• Type

  @interface WeChatPayKKaHandler : NSObject

• Methods

  + (instancetype)shared;
  + (BOOL)handleOpenURL:(NSURL *)url;
  + (BOOL)handleUniversalLink:(NSUserActivity *)userActivity;

  WeChatPayKKaHandler.shared()
  WeChatPayKKaHandler.handleOpen(_ url: URL) -> Bool
  WeChatPayKKaHandler.handleUniversalLink(_ userActivity: NSUserActivity) -> Bool

• Details

  • handleOpenURL:: Handles a URL Scheme callback.
  • handleUniversalLink:: Handles a Universal Link callback.
  • Returns YES when WeChatOpenSDK accepts the callback; returns NO if a dependency is missing or a runtime invocation fails.
  • The merchant app should call the public forwarding methods above and must not pass WeChatPayKKaHandler.shared directly to WXApi.

• Example

  - (void)scene:(UIScene *)scene
      openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
      NSURL *url = URLContexts.anyObject.URL;
      if (url) {
          [WeChatPayKKaHandler handleOpenURL:url];
      }
  }
  
  - (void)scene:(UIScene *)scene
      continueUserActivity:(NSUserActivity *)userActivity {
      [WeChatPayKKaHandler handleUniversalLink:userActivity];
  }

  .onOpenURL { url in
      _ = WeChatPayKKaHandler.handleOpen(url)
  }
  .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
      _ = WeChatPayKKaHandler.handleUniversalLink(activity)
  }

An object containing the normalized payment result and raw payment data.

• Type

  @interface PKPaymentResult : NSObject

• Properties

  • status (PKPaymentStatus): The payment status.
  • message (NSString *, nullable): The result message or error information.
  • result (NSDictionary *, nullable): The raw payment result data.
  • paymentResultObj (NSDictionary *): The complete dictionary representation of the payment result.

Creates a payment result object using a payment status, raw result, and message.

• Type

  - (instancetype)initWithStatus:(PKPaymentStatus)status
                          result:(nullable NSDictionary *)result
                         message:(nullable NSString *)message;

  PKPaymentResult(
      status: PKPaymentStatus,
      result: [AnyHashable: Any]?,
      message: String?
  )

Payment status enumeration:

• PKPaymentStatusUnknown / .unknown: Unknown status.
• PKPaymentStatusSuccess / .success: Payment successful.
• PKPaymentStatusExpired / .expired: The payment or Checkout Session has expired.
• PKPaymentStatusError / .error: An error occurred during payment.

Converts between a payment result object and a JSON string.

• Type
  + (instancetype)fromString:(NSString *)jsonString;
  - (NSString *)toString;