Flutter SDK（faststar_pay）

官方 Flutter SDK 在 App 内以全屏 WebView 打开 FastStar 托管收银台，支付结果通过回调返回，无需自行处理 WebView 细节。

安装

dependencies:
  faststar_pay: ^1.0.0

本包依赖 webview_flutter ^4.0.0：

• Android：minSdkVersion 19（建议 21+）
• iOS：iOS 12.0+，无需额外配置

打开收银台

import 'package:faststar_pay/faststar_pay.dart';

await FastStarCheckout.open(
  context,
  url: checkoutUrl, // 服务端创建的 Checkout Session url，或支付链接
  onSuccess: (data) {
    // 支付成功（履约请以服务端 Webhook 为准）
    debugPrint('支付成功 payment_intent_id=${data['payment_intent_id']}');
  },
  onCancel: () {
    debugPrint('用户取消支付');
  },
  onError: (data) {
    debugPrint('支付失败: ${data['message']}');
  },
);

open() 会 push 一个全屏结算页面，包含：

• AppBar 关闭按钮（点击触发 onCancel）
• 页面加载进度条
• 系统返回手势同样映射为 onCancel

返回值方式（不用回调）

open() 同时返回 Future<FastStarCheckoutResult>，可直接 await：

final result = await FastStarCheckout.open(context, url: payUrl);

switch (result.event) {
  case FastStarCheckoutEvent.success:
    print('成功: ${result.data}');
  case FastStarCheckoutEvent.cancel:
    print('取消');
  case FastStarCheckoutEvent.error:
    print('失败: ${result.data}');
}

结果回传机制：FastStarBridge + URL 兜底

SDK 通过两条通道接收结算页的支付结果，任一通道触发即生效，回调保证只触发一次：

1. JS 桥接（主通道）：SDK 注入名为 FastStarBridge 的 JavaScript 通道，托管结算页调用：

   window.FastStarBridge.postMessage(JSON.stringify({
     event: 'checkout.success', // checkout.success | checkout.cancel | checkout.error
     data: { payment_intent_id: 'pi_xxx' }
   }));

   通道只接受字符串，因此消息体需 JSON.stringify；与 iframe 消息格式不同，这里不需要 source 字段（通道本身已隔离）。同时兼容简写事件名 success / cancel / error。
2. URL 拦截（兜底）：结算页重定向到你的 success_url / cancel_url 且 URL 携带 faststar_status=success|cancel|error 查询参数时，SDK 会拦截跳转、关闭结算页面并触发对应回调；URL 上的其余查询参数（如 payment_intent_id）会作为 data 透传给回调。因此即使结算页未调用桥接，只要正常重定向，回调依然有效。

注意事项

• onSuccess 仅用于客户端交互（关页面、跳转成功页等）。订单履约必须以 FastStar 服务端 Webhook 为准。
• 结算页内的 3DS 银行验证跳转会在同一 WebView 内完成，无需额外处理。