跳转到内容

快速接入

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

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

步骤一:在项目中引入 SDK

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

.
├── libs
│   └── paykka-checkout-payments-1.0-alpha-Release.aar
└── PayKKaCheckoutApp-Android
    ├── JavaCheckoutDemo
    │   ├── app
    │   ├── build.gradle
    │   ├── gradle
    │   ├── gradle.properties
    │   ├── gradlew
    │   ├── gradlew.bat
    │   └── settings.gradle
    └── KotlinCheckoutDemo
        ├── app
        ├── build.gradle.kts
        ├── gradle
        ├── gradle.properties
        ├── gradlew
        ├── gradlew.bat
        └── settings.gradle.kts

其中,PayKKaCheckoutApp-Android 包含用 Java 和 Kotlin 语言编写的示例 App 的 Android 项目工程,开发者可以通过示例代码了解 PayKKa SDK 的 API 使用方式。

libs 文件夹下的 .aar 文件就是 PayKKa 的基础 SDK。将上述 zip 文件中的 libs 文件夹复制到您的 Android 项目中的 app/ 文件夹下,例如 YourAppProject/app/。然后编辑 app/build.gradle.ktsapp/build.gradle 文件,加入以下代码以引入和使用 SDK:

app/build.gradle.kts
plugins {
    ...
}

android {
    ...
}

dependencies {
    ...
    // 必须,用于JSON序列化/反序列化
    implementation("com.alibaba:fastjson:1.2.83")
    // 必须,sdk用到了webkit的一些特性
    implementation("androidx.webkit:webkit:1.14.0")
    // 必须,引入libs目录下的所有库和依赖
    implementation(
        fileTree(
            mapOf(
                "dir" to "libs",
                "include" to listOf("*.aar", "*.jar")
            )
        )
    )
}

步骤二:在项目中使用 SDK

SDK 引入后,就可以在您的 App 内集成和使用 PayKKa 的收银台了。下面列出了一些关键代码,通过调用 SDK 的方法,便可以自定义回调并拉起收银台,引导用户完成付款操作。

import ...

class ConfirmOrderActivity : ComponentActivity() {
    val TAG = "ConfirmOrderActivity"
    private lateinit var paykkaLauncher: PayKKaActivityResultLauncher;
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 一定要在Activity onCreate 之前完成 registerForActivityResult
        paykkaLauncher = PayKKa.registerForActivityResult(this) {paymentResult ->
            // 在这里写您的支付回调逻辑
            val intent = Intent(this, PaymentCompleteActivity::class.java)
            intent.putExtra("paymentResult", paymentResult.toString())
            startActivity(intent)
            finish()
        }

        setContent {
            KotlinCheckoutDemoTheme {
                ConfirmOrderScreen {
                    goPay()
                }
            }
        }
    }

    private fun goPay() {
        // 切换 PayKKa 环境
        PayKKa.useEnv(PayKKaEnv.SANDBOX)
        // 点击“确认支付”按钮,拉起收银台(此收银台sessionId,一般由App后端接口返回)
        paykkaLauncher.goPay("CSXXXXXXXXXXXXXXXXXX")
    }

    override fun onActivityResult(
        requestCode: Int,
        resultCode: Int,
        data: Intent?
    ) {
        super.onActivityResult(requestCode, resultCode, data)
    }
}

步骤三:测试支付

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

/// SANDBOX(默认)
PayKKa.useEnv(PayKKaEnv.SANDBOX)
/// 切换到EU生产环境
PayKKa.useEnv(PayKKaEnv.PROD_EU)
/// 切换到HK生产环境
PayKKa.useEnv(PayKKaEnv.PROD_HK)

注意事项

Google Pay

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

请参阅:Payment Method - Google Pay

2. PROD 环境下 Google Pay 无法接收付款,提示 “OR_BIBED_11”

Google Pay 在测试环境下使用的是测试环境和模拟数据;但上线后会处理真实的用户付款卡信息。为了保护用户和商户的资金与隐私安全,Google 要求:

  • 有支持的支付网关(例如 PayKKa)或
  • 拥有符合 PCI DSS(支付卡行业数据安全标准)的环境才能申请生产访问权限。这样可以确保您有能力安全处理敏感支付信息,而不是仅在开发测试模式下运行。

因此,您还需要完成 Google Pay - 发布集成 步骤。