# SDK接口文档 ## 全局配置与初始化 ### PayKKaEnvironment SDK 环境接口，用于定义 API 域名、收银台 URL、Google Pay 网关参数和 3DS 环境等配置。 - **类型** ```java public interface PayKKaEnvironment ``` - **详细信息** - 你可以通过实现此接口扩展自定义环境。 - SDK 内置实现为 `PayKKaEnv` 枚举，常用环境包括： - `SANDBOX` - `PROD_EU` - `PROD_HK` ### PayKKaEnv `PayKKaEnvironment` 的内置实现（枚举）。 - **类型** ```java public enum PayKKaEnv implements PayKKaEnvironment ``` - **枚举值** - `SANDBOX`: 沙箱测试环境。 - `PROD_EU`: 欧洲生产环境。 - `PROD_HK`: 香港生产环境。 ### PayKKaConfiguration 商户配置接口。你可以实现此接口定义自己的商户参数。 - **类型** ```java public interface PayKKaConfiguration ``` - **配置选项** - `GatewayMerchantId`（`getGatewayMerchantId()`）：网关商户 ID。 - `ClientKey`（`getClientKey()`）：客户端密钥。 - `Locale`（`getLocale()`）：语言/地区，默认可为空。 - `WeChatPayAppId` (`getWeChatPayAppId`)：微信开放平台的AppID，默认可为空。 - `AlipayPlusAcquirerId` (`getAlipayPlusAcquirerId`)：Alipay+开发者平台的`Participant ID`，默认可为空。 ### PayKKa.useEnv() 全局切换当前 SDK 使用的环境。 - **类型** ```java public static void useEnv(PayKKaEnvironment env) ``` - **详细信息** 在支付前调用即可生效，影响后续接口请求和收银台行为。 ### PayKKa.useConf() 全局切换当前 SDK 使用的商户配置。 - **类型** ```java public static void useConf(PayKKaConfiguration conf) ``` - **详细信息** 设置后会作为后续支付流程的默认商户配置。 ### PayKKa.init() 初始化 SDK，并使环境、商户配置、语言配置生效。 - **类型** ```java public static void init( @NonNull ComponentActivity contextActivity, PayKKaConfiguration configuration, PayKKaEnvironment environment ) public static void init( @NonNull ComponentActivity contextActivity, PayKKaConfiguration configuration ) ``` - **详细信息** - 推荐在支付宿主页面初始化阶段调用。 - `environment` 为空时默认使用 `PayKKaEnv.SANDBOX`。 - 会根据 `configuration.getLocale()` 应用全局 i18n 语言。 ### PayKKa.goPay() 注意 此方法已废弃，后续版本不再兼容。请优先使用 Drop-In（`PaymentBottomSheet`）方式拉起收银台。 details summary 展示 WebView 形式收银台。 - **类型** ```java @Deprecated public static void goPay( Activity context, String sessionId, PaymentResultCallback onPaymentResultCallback ) @Deprecated public static void goPay( Activity context, String sessionId, PaymentResultCallback onPaymentResultCallback, JSEventCallback onCloseTappedCallback ) ``` - **详细信息** - `context`：发起支付的 `Activity`。 - `sessionId`：服务端创建的支付会话 ID。 - `onPaymentResultCallback`：支付结果回调。 - `onCloseTappedCallback`（可选）：用户点击关闭事件回调。 ## 网络与数据转换 ### PayKKaHttpClient 全局单例 HTTP 客户端，基于 OkHttp 封装。 - **类型** ```java public final class PayKKaHttpClient ``` - **详细信息** - 负责请求构建与发送。 - 自动设置/合并默认请求头（如 SDK 版本、应用信息、语言等）。 - 提供统一的响应解析与错误处理。 ### CheckoutApi 收银台核心业务接口。 - **类型** ```java public class CheckoutApi extends ApiBase ``` - **必要配置属性** - `checkoutSessionId` - `clientKey` - **方法** - `requestComponentCheckoutSessionInfo()`：获取收银台会话信息。 - `requestComponentCheckoutSessionPaymentsQuery()`：查询会话支付状态。 - `createCheckoutSessionPayments(...)`：提交支付请求。 - `request3DSParamsQuery(...)`：查询 3DS 参数。 - `request3DSCallback(...)`：触发 3DS 回调确认。 ### PublicApi 公共能力接口，全局单例。 - **类型** ```java public class PublicApi extends ApiBase ``` - **方法** - `requestPubDataDictGet(...)`：获取数据字典。 - `requestAddressProvinceDict(...)`：获取省/州数据。 - `requestAddressCityDict(...)`：获取城市数据。 - `requestAddressStyle(...)`：获取地址表单样式配置。 - `requestPubChannelSdkConfig(...)`：获取渠道 SDK 配置。 ### DTO（数据模型对象） SDK 使用 Java 对象承载请求/响应和业务字段，主要位于： - `com.paykka.android.checkout.model` - `com.paykka.android.checkout.model.dto` - `com.paykka.android.checkout.model.dto.enums` 常见对象包括支付载荷、会话信息、账单地址、支付方式、枚举类型等。 ## 用户界面 ### GooglePayment 用于发起 Google Pay 支付流程。 - **类型** ```java public final class GooglePayment extends PaymentBase ``` - **方法** - `requestPayment(String checkoutSessionId, PaymentResultCallback paymentResultCallback)`：发起 Google Pay 支付并处理结果。 ### GooglePaymentForm Google Pay 按钮组件（`LinearLayout`）。 - **类型** ```java public class GooglePaymentForm extends LinearLayout ``` - **方法** - `showLoadingOverlay()`：显示加载遮罩。 - `hideLoadingOverlay()`：隐藏加载遮罩。 ### WeChatPayment 用于发起微信支付流程。 - **类型** ```java public class WeChatPayment extends PaymentBase ``` - **方法** - `init(WeChatPaymentForm weChatPaymentForm, String checkoutSessionId, WeChatPaymentFormInitCallback initCallback)`：绑定微信支付表单与支付会话，并初始化微信支付能力。 - `requestPayment(PaymentResultCallback paymentResultCallback)`：创建微信支付订单、拉起微信 App 支付，并处理支付结果、用户取消和异常回调。 - **详细信息** - 调用 `requestPayment(...)` 前需要先完成 `init(...)`。 - 依赖商户配置中的 `getWeChatPayAppId()`，用于完成微信开放平台相关初始化。 ### WeChatPaymentForm 微信支付表单组件（`LinearLayout`）。 - **类型** ```java public class WeChatPaymentForm extends LinearLayout ``` - **详细信息** - 该组件用于展示微信支付表单区域和错误提示信息。 - 当前无额外输入项，主要用于承载支付说明和错误态展示。 ### AlipayPlusPayment 用于发起 Alipay+ 支付流程。 - **类型** ```java public class AlipayPlusPayment extends PaymentBase ``` - **方法** - `init(AlipayPlusPaymentForm alipayPlusPaymentForm, String checkoutSessionId, AlipayPaymentFormInitCallback initCallback)`：绑定 Alipay+ 支付表单、支付会话，并初始化 Alipay+ SDK 配置。 - `requestPayment(PaymentResultCallback paymentResultCallback)`：创建 Alipay+ 支付订单、展示支付面板，并处理支付结果、取消和异常回调。 - **详细信息** - 调用 `requestPayment(...)` 前需要先完成 `init(...)`。 - 依赖商户配置中的 `getAlipayPlusAcquirerId()`，用于初始化 Alipay+ 渠道配置。 - 从外部钱包或页面返回应用后，SDK 会在合适的生命周期中自动轮询支付状态并继续完成结果回调。 ### AlipayPlusPaymentForm Alipay+ 支付表单组件（`LinearLayout`）。 - **类型** ```java public class AlipayPlusPaymentForm extends LinearLayout ``` - **详细信息** - 该组件用于展示 Alipay+ 支付表单区域和错误提示信息。 - 当前无额外输入项，主要用于承载支付说明和错误态展示。 ### BankCardPayment 用于发起银行卡支付流程。 - **类型** ```java public class BankCardPayment extends PaymentBase ``` - **方法** - `init(CardPaymentForm cardPaymentForm, String checkoutSessionId, CardPaymentFormInitCallback initCallback)`：初始化卡支付实例与会话上下文。 - `requestPayment(PaymentResultCallback paymentResultCallback)`：校验并提交银行卡支付。 ### CardPaymentForm 银行卡支付表单组件（`LinearLayout`）。 - **类型** ```java public final class CardPaymentForm extends LinearLayout ``` - **方法** - `init(Context context)`：初始化表单视图与输入组件。 - `setInputValidationListener(InputValidationListener listener)`：监听输入校验状态。 - `setEnabled(boolean enabled)`：启用/禁用表单输入。 - `hideKeyboard()`：收起键盘。 - `clearAllInputFocus()`：清除全部输入焦点。 ### PaymentBottomSheet Drop-In 收银台底部弹窗（`BottomSheetLayout`）。 - **类型** ```java public final class PaymentBottomSheet extends BottomSheetLayout ``` - **方法** - `showMerchantName()`：显示商户名称区域。 - `init(String checkoutSessionId, OnSheetCloseCallback onSheetCloseCallback)`：初始化会话与关闭回调。 - `show(OnSheetLoadedCallback onLoadedCallback)` / `show()`：展示收银台。 - `hide()`：关闭收银台。 ## 其他数据类型 ### PaymentResult 支付结果对象。 - **属性** - `getStatus()`: 返回 `PaymentResult.Status` 枚举。 - `getResult()`: 返回 `JSONObject`，包含详细支付结果数据。 - `getMessage()`: 返回结果描述信息。 - **PaymentResult.Status 枚举** - `SUCCESS`: 支付成功。 - `EXPIRED`: 支付过期。 - `ERROR`: 支付错误。 - `UNKNOWN`: 未知状态。 ### JSEvent 注意 已废弃，后续版本不再兼容。 details summary 来自支付页面的 JavaScript 事件。 - **属性** - `getType()`: 返回 `JSEvent.JSEventType`。 - `getData()`: 返回事件携带的 `JSONObject` 数据。 - **JSEvent.JSEventType 枚举** - `CLOSE_TAPPED`: 用户点击支付页面关闭/返回按钮。 - `UNKNOWN`: 未知事件。