# 快速接入

> 阅读此文档前，确保您已完成 [集成指南](/zh-hans/payments/docs/introduction/integrated-guide)，并了解了 [创建收银台的相关 API](/zh-hans/payments/apis/introduction/started)。


PayKKa 提供的 Android SDK 可以方便您直接以 WebView 的方式嵌入 [Web 收银台](/zh-hans/payments/docs/transaction/web/hosted-web)，只需传给 SDK 一个 `sessionId` 即可在 App 内打开收银台页面，接收用户的付款，并且可以自定义和处理相关的支付回调。SDK 最新的下载地址可以在 [Android SDK 历史版本和更新日志](/zh-hans/payments/docs/developer-resources/native-sdks/android-sdk/release-history) 中找到。

## 步骤一：在项目中引入 SDK

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


```txt
.
├── 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.kts` 或 `app/build.gradle` 文件，加入以下代码以引入和使用 SDK：

Kotlin

```kotlin 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")
            )
        )
    )
}
```

Java

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

android {
    ...
}

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

## 步骤二：在项目中使用 SDK

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

Kotlin

```kotlin ConfirmOrderActivity.kt
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)
    }
}
```


```kotlin PaymentCompleteScreen.kt
import ...

@Composable
fun PaymentCompleteScreen(
    paymentResult: PaymentResult
) {
    val (imageRes, text) = when (paymentResult.status) {
        // 收银台支付成功
        PaymentResult.Status.SUCCESS ->
            R.drawable.icon_check_circle_24px to "Pay Success"
        // 收银台会话过期
        PaymentResult.Status.EXPIRED ->
            R.drawable.icon_warning_24px to
                    "The checkout session has expired. Please initiate the payment again."
        PaymentResult.Status.ERROR ->
            R.drawable.icon_cancel_24px to
                    "Failed, please try again later"
        else ->
            R.drawable.icon_warning_24px to "Unknown Payment status"
    }
    Scaffold { _ ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(24.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
        ) {
            Image(
                painter = painterResource(id = imageRes),
                contentDescription = null,
                modifier = Modifier
                    .size(110.dp),
                contentScale = ContentScale.Fit
            )
            Spacer(
                modifier = Modifier.height(100.dp)
            )
            Text(
                text = text,
                fontSize = 16.sp,
                color = MaterialTheme.colorScheme.onBackground,
                textAlign = TextAlign.Center
            )
        }
    }

}
```


```kotlin PaymentCompleteActivity.kt
import ...

// App支付结果展示界面
class PaymentCompleteActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val statusString = intent.getStringExtra("paymentResult")
        val paymentResult = PaymentResult.fromString(statusString)
        setContent {
            KotlinCheckoutDemoTheme {
                PaymentCompleteScreen(paymentResult = paymentResult)
            }
        }
    }
}
```

Java

```java ConfirmOrderActivity.java
...

public class ConfirmOrderActivity extends AppCompatActivity {
    Button btnPay;
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_confirm_order);

        Activity context = this;
        // 切换PayKKa收银台的环境
        PayKKa.useEnv(PayKKaEnv.SANDBOX);
        btnPay = findViewById(R.id.btn_pay);
        btnPay.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                // 点击“确认支付”按钮，拉起收银台（此收银台sessionId，一般由App后端接口返回）
                PayKKa.goPay(context, "CSXXXXXXXXXXXXXXXXXX", (paymentResult) -> {
                    // 在这里写您的支付回调逻辑
                    Intent intent = new Intent(context, PaymentComplete.class);
                    intent.putExtra("paymentResult", paymentResult.toString());
                    startActivity(intent);
                    context.finish();
                });
            }
        });
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        // ⚠️注意：必须确保onActivityResult中调用了PayKKa.onPaymentResult，这样才能触发您预设的支付回调逻辑
        PayKKa.onPaymentResult(requestCode, resultCode, data);
    }
}
```


```java PaymentComplete.java
...

// App支付结果展示界面
public class PaymentComplete extends AppCompatActivity {

    ImageView statusImage;
    TextView statusText;

    PaymentResult paymentResult;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment_complete);

        statusImage = findViewById(R.id.statusImage);
        statusText = findViewById(R.id.statusText);

        String status = getIntent().getStringExtra("paymentResult");
        paymentResult = PaymentResult.fromString(status);

        updateUI(paymentResult);
    }

    private void updateUI(PaymentResult paymentResult) {
        int imgResourceId = R.drawable.icon_warning_24px;
        String text = "Unknown Payment status";
        switch (paymentResult.getStatus()) {
            // 收银台支付成功
            case SUCCESS:
                imgResourceId = R.drawable.icon_check_circle_24px;
                text = "Pay Success";
                break;
            // 收银台会话过期
            case EXPIRED:
                imgResourceId = R.drawable.icon_warning_24px;
                text = "The checkout session has expired. Please initiate the payment again.";
                break;
            case ERROR:
                imgResourceId = R.drawable.icon_cancel_24px;
                text = "Failed, please try again later";
                break;
        }
        statusImage.setImageResource(imgResourceId);
        statusText.setText(text);
    }
}
```

## 步骤三：测试支付

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

Kotlin

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

Java

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

## 注意事项

### Google Pay

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

请参阅：[Payment Method - Google Pay](/zh-hans/payments/docs/payment-method/google-pay/google-pay#%E6%B5%8B%E8%AF%95-google-pay)。

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

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

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


因此，您还需要完成 [Google Pay - 发布集成](https://developers.google.com/pay/api/android/guides/test-and-deploy/publish-your-integration) 步骤。