Flutter WebView加载Mastercard Hosted Checkout仅显示加载动画的问题求助

架构老林

2026-6-13

问题

我在Flutter应用中使用WebView集成Mastercard Payment Gateway Hosted Checkout，计划通过后端获取的Session ID（API版本83，测试环境）打开Mastercard支付门户，但支付门户仅显示加载动画，实际支付页面始终无法加载，控制台日志报错如下：

Flutter代码实现

void loadPaymentPage() {
  print('Step: Starting loadPaymentPage at ${DateTime.now()}');
  if (sessionId == null) {
    print('Step: Session ID is null - Aborting loadPaymentPage at ${DateTime.now()}');
    return;
  }
  print('Step: Session ID available - $sessionId at ${DateTime.now()}');

  String htmlContent = """
<!DOCTYPE html>
<html>
<head>
  <script src="https://test-xxx.gateway.mastercard.com/static/checkout/checkout.min.js"
          data-error="errorCallback"
          data-cancel="cancelCallback"></script>
  <script type="text/javascript">
    function errorCallback(error) {
      console.log(JSON.stringify(error));
    }
    function cancelCallback() {
      console.log('Payment cancelled');
    }
    window.onload = function() {
      Checkout.configure({
        session: {
          id: '$sessionId'
        }
      });
      Checkout.showPaymentPage();
    };
  </script>
</head>
<body>
  <p>Loading payment...</p>
  <div id="embed-target"></div>
  <input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" />
  <input type="button" value="Pay with Payment Page" onclick=";" />
</body>
</html>
""";

  _controller.loadHtmlString(htmlContent);
}

控制台错误日志

Possible Unhandled Promise Rejection: [object DOMException]
Unrecognized feature: 'payment'.
Uncaught SecurityError: Failed to read the 'sessionStorage' property from 'Window': Access is denied for this document.

请问如何解决Flutter WebView中传入Session ID后Mastercard支付网关门户无法加载的问题？是否需要特殊的WebView设置、权限或变通方案才能让Mastercard Hosted Checkout在Flutter中正常工作？

解决方案

1. 强制开启WebView的JavaScript与存储权限

Mastercard Checkout脚本依赖sessionStorage和完整的JavaScript支持，必须在WebView配置中明确开启相关权限：

WebView(
  controller: _controller,
  javascriptMode: JavascriptMode.unrestricted, // 核心：开启全量JS支持
  initialUrl: 'about:blank',
  onWebViewCreated: (controller) {
    _controller = controller;
  },
  // Android端配置
  androidSettings: AndroidSettings(
    domStorageEnabled: true, // 开启DOM存储（sessionStorage依赖）
    databaseEnabled: true,
    allowFileAccess: true,
    allowContentAccess: true,
  ),
  // iOS端配置
  iosSettings: IosSettings(
    javaScriptEnabled: true,
    domStorageEnabled: true,
  ),
)

2. 放弃本地HTML加载，直接跳转至Mastercard官方支付页面

本地HTML加载会触发跨域和存储权限限制，建议直接构造Mastercard官方支付URL进行加载：

// 替换为你的测试网关域名
String paymentUrl = "https://test-xxx.gateway.mastercard.com/checkout/payment?sessionId=$sessionId";
_controller.loadUrl(paymentUrl);

这种方式让支付脚本在Mastercard自有域名环境下运行，完全规避本地HTML带来的权限问题。

3. 配置导航代理允许Mastercard域名跳转

如果必须使用本地HTML，需通过NavigationDelegate允许WebView与Mastercard网关域名交互：

navigationDelegate: (NavigationRequest request) {
  if (request.url.startsWith('https://test-xxx.gateway.mastercard.com')) {
    return NavigationDecision.navigate;
  }
  return NavigationDecision.prevent;
},

4. 验证Session ID有效性

测试环境下Mastercard Session ID有效期较短，需确保后端返回的Session ID未过期、格式正确，且与测试网关环境匹配。

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

Flutter WebView加载Mastercard Hosted Checkout仅显示加载动画的问题求助

问题 #

Flutter代码实现 #

控制台错误日志 #

解决方案 #

1. 强制开启WebView的JavaScript与存储权限 #

2. 放弃本地HTML加载，直接跳转至Mastercard官方支付页面 #

3. 配置导航代理允许Mastercard域名跳转 #

4. 验证Session ID有效性 #

问题