Google Play上架后Stripe Terminal Tap to Pay功能异常求助

问题现象 #

• 应用发布至Google Play商店后，Stripe Terminal的Tap to Pay功能无法启动，支付界面无法显示
• 直接测试本地打包的Release APK时，功能完全正常
• 已确认应用已获取全部必要权限

报错日志 #

Error creating payment intent: live TerminalException: declinedByStripeApi
I/flutter (19401): You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). 
I/flutter (19401): ApiError(error=InnerError(charge=null, code=null, declineCode=null, docUrl=null, message=You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). , param=null, paymentIntent=null, setupIntent=null, type=INVALID_REQUEST_ERROR))
I/flutter (19401): com.stripe.stripeterminal.external.models.TerminalException: You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). S
E/flutter (19401): [ERROR:flutter/runtime/dart_vm_initializer.cc(40)] Unhandled Exception: Null check operator used on a null value
E/flutter (19401): #0      PosMenuController.proceedTapToPay.<anonymous closure> (package:reatiler_pos/app/modules/pos_menu/controllers/pos_menu_controller.dart:4821)

相关代码片段 #

final paymentIntent =
          await terminal.createPaymentIntent(PaymentIntentParameters(
        amount: (double.parse(double.parse(amount).toStringAsFixed(2)) * 100)
            .ceil(),
        currency: "USD", // 你的货币类型
        customerId: _customer?.id,
        captureMethod: CaptureMethod.automatic,
        paymentMethodTypes: [PaymentMethodType.cardPresent],
      ));

排查与解决方案 #

1. Google Play App Signing导致的密钥配置问题 #

Google Play的App Signing会替换应用签名证书，可能引发以下问题：

• 本地配置的Stripe密钥未正确注入发布版应用
• 签名证书未添加到Stripe后台白名单，导致API请求被拦截

解决步骤：

• 登录Google Play Console，进入「应用签名」页面，复制发布证书的SHA-1/SHA-256值，添加到Stripe后台的应用白名单中
• 检查android/app/build.gradle的release构建配置，确保密钥通过环境变量安全注入，避免硬编码：

  buildTypes {
      release {
          signingConfig signingConfigs.release
          resValue "string", "stripe_publishable_key", "\"${System.getenv('STRIPE_PUBLISHABLE_KEY')}\""
      }
  }
  

• 在proguard-rules.pro中添加Stripe混淆排除规则，防止相关类被混淆：

  -keep class com.stripe.** { *; }
  -keep class com.stripe.android.** { *; }
  -keep class com.stripe.stripeterminal.** { *; }
  

2. 环境密钥未切换 #

本地测试用的是Stripe测试密钥，发布到Google Play时未切换为生产密钥，或生产密钥权限不足。

解决步骤：

• 登录Stripe后台，确认已生成生产环境API密钥，且该密钥拥有Terminal相关权限
• 在代码中根据构建模式自动切换密钥：

  import 'package:flutter/foundation.dart';
  
  String get stripePublishableKey {
    return kReleaseMode ? '生产环境密钥' : '测试环境密钥';
  }
  

3. 空值异常处理 #

报错中的空值异常是因为terminal对象未初始化或paymentIntent返回null时直接使用了空值运算符。

解决步骤：

• 调用支付接口前先检查terminal状态，添加异常捕获：

  if (terminal == null) {
    // 提示用户终端未初始化，可尝试重启应用
    return;
  }
  
  try {
    final paymentIntent = await terminal.createPaymentIntent(PaymentIntentParameters(
      amount: (double.parse(double.parse(amount).toStringAsFixed(2)) * 100).ceil(),
      currency: "USD",
      customerId: _customer?.id,
      captureMethod: CaptureMethod.automatic,
      paymentMethodTypes: [PaymentMethodType.cardPresent],
    ));
    // 处理支付意向创建成功的逻辑
  } catch (e) {
    // 捕获异常并提示用户，避免崩溃
    print('支付意向创建失败: $e');
    // 显示错误提示给用户
  }
  

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