Android设备Stripe Tap on Mobile报错追踪与界面定制问题

背景 #

基于Stripe Terminal Android实现Tap on Mobile功能，使用版本：

com.stripe:stripeterminal:2.15.0
com.stripe:stripeterminal-localmobile:2.15.0

应用架构为MainActivity + 两个Fragment：Fragment1负责金额选择（默认启动页），Fragment2处理读卡器连接与支付流程，当前存在NFC界面定制、错误场景显示及页面跳转问题，以下是针对性解决方案：

1. 自定义NFC读卡界面视图 #

Stripe Terminal v2.15.0中，Tap on Mobile触发的NFC读卡界面是系统级NFC服务提供的原生界面，SDK不支持完全自定义布局（如替换背景、按钮样式等）。但可通过CollectConfiguration做有限的文案定制：

val collectConfig = CollectConfiguration.Builder()
    .setCollectPaymentMethodMessage("请将卡片贴近设备NFC感应区") // 自定义提示文本
    .updatePaymentIntent(true)
    .build()

若需完全自定义界面，需自行集成Android原生NFC框架，但会丢失Stripe Terminal提供的支付安全验证、卡片数据加密等核心能力，不推荐此方案。

2. 测试模式下真实卡片的错误场景定制 #

测试模式下使用真实卡片时，collectPaymentMethod仅负责读取卡片物理信息（会触发系统成功绿屏），但processPayment会返回"使用非测试卡片"的错误。需在processPayment的失败回调中拦截该错误并自定义提示：

Terminal.getInstance().processPayment(paymentIntent, object : PaymentIntentCallback {
    override fun onSuccess(paymentIntent: PaymentIntent) {
        // 原有成功逻辑
        Log.d("Custom Log","Process Payment : "+paymentIntent.id);
    }

    override fun onFailure(exception: TerminalException) {
        val errorMessage = exception.errorMessage ?: "支付处理失败"
        // 拦截测试模式下的真实卡片错误
        if (errorMessage.contains("non test (live) card")) {
            // 自定义错误弹窗
            AlertDialog.Builder(requireContext())
                .setTitle("测试模式提示")
                .setMessage("请使用Stripe官方测试卡片进行测试，例如：4242 4242 4242 4242")
                .setPositiveButton("知道了") { dialog, _ -> dialog.dismiss() }
                .show()
        } else {
            // 其他错误场景处理
            Toast.makeText(requireContext(), errorMessage, Toast.LENGTH_LONG).show()
        }
    }
})

3. 捕获NFC界面关闭事件并跳转至Fragment2 #

系统NFC界面关闭后，会触发collectPaymentMethod的onSuccess或onFailure回调，可在这两个回调中主动执行Fragment跳转逻辑，替代默认的Fragment1跳转：

1. 在MainActivity中添加跳转方法：

fun navigateToFragment2() {
    supportFragmentManager.beginTransaction()
        .replace(R.id.fragment_container, Fragment2()) // 替换为你的布局容器ID
        .addToBackStack(null)
        .commit()
}

2. 在collectPaymentMethod的回调中调用该方法：

val cancelable = Terminal.getInstance().collectPaymentMethod(paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // 原有支付逻辑...
            // 跳转回Fragment2
            (activity as? MainActivity)?.navigateToFragment2()
        }

        override fun onFailure(exception: TerminalException) {
            // 原有错误处理...
            // 跳转回Fragment2
            (activity as? MainActivity)?.navigateToFragment2()
        }
    })

内容的提问来源于stack exchange，提问作者Ajith