Google Pay

集成路线图

如果你是第一次接入 Google Pay，按以下顺序走：

%%{init: {"flowchart": {"htmlLabels": true, "curve": "basis"}, "themeVariables": {"fontSize": "20px"}}}%%
flowchart LR
    A["1. SDK 初始化<br/>new LegendBase()<br/>+ 登录授权"] --> B["2. canSetupGooglePay()<br/>检测设备能力"]
    B --> C["3. setupGooglePay()<br/>挂载 Google Pay 按钮<br/>到指定容器"]
    C --> D["4. 处理结果<br/>onPay / onError<br/>回调返回订单数据"]

UI 触发时机

集成路线图讲的是「SDK 方法是什么」；这一节讲的是「在交易所自己的 UI 上，用户的哪个动作触发哪个 SDK 调用」。

%%{init: {"sequence": {"actorMargin": 60, "messageMargin": 35}, "themeVariables": {"fontSize": "16px"}}}%%
sequenceDiagram
    autonumber
    participant U as 用户
    participant E as 交易所页面
    participant SDK as Legend Base SDK
    participant G as Google Pay 浮层

    U->>E: 进入购买页
    E->>SDK: canSetupGooglePay()
    SDK-->>E: true / false
    E->>SDK: setupGooglePay({...})
    SDK-->>E: 在指定容器内挂载 Google Pay 按钮

    U->>E: 填金额、选 Google Pay
    U->>E: 点击 Google Pay 按钮
    SDK-->>E: onPay('clicked') → 开 loading
    SDK->>G: 自动唤起 Google Pay 支付浮层
    SDK-->>E: onPay('authorizing') → 可关 loading
    U->>G: 选卡 + 授权
    G-->>SDK: walletToken
    SDK-->>E: onPay('processing') → 重新开 loading
    SDK->>SDK: 自动下单（Sandbox 可达 20-40s）
    SDK-->>E: 触发 onPay / onError 回调
    E-->>U: 显示 success / failed UI

用户若在浮层中主动关闭，SDK 触发 onPay('cancelled')（不是 onError）。

UI 时机速查表

在开始集成前我们建议阅读下面的文档说明：

• 开始使用
• Google Pay API Overview

当前网页的支付流程

• 调用canSetupGooglePay()方法，获取当前运行环境是否支持 Google Pay。

const resp = await legend.canSetupGooglePay()
console.log("canSetupGooglePay: \n", resp);

调用前请确保页面中已有匹配 wrapperSelector 的 DOM 元素（例如 <div class="google-pay-wrapper"></div>），Google Pay 按钮会插入到该元素内部。

• 调用setupGooglePay()方法，初始化 Google Pay 的支付按钮。

await legend.setupGooglePay({
  wrapperSelector: '.google-pay-wrapper',
  button: {
    buttonColor: 'default', // 'default' | 'black' | 'white'
    buttonType: 'buy',      // 'buy' | 'pay' | 'plain' | 'donate' | 'short' | 'subscribe'
  },
  order: {
    app_state, // 合作伙伴自定义的订单关联字符串，会原样回传给回调
    network: "ETH",
    pair: "USDCUSD",
    side: "buy",
    size: "50",
    external_order_id: `otcsb-googlepay-${Date.now().toString()}`
  }
});

按钮注入后用户点击会自动唤起 Google Pay 支付，授权完成后 SDK 自动下单。支付结果通过 LegendBase 构造时传入的 onPay / onError 回调返回，详见 前端集成 中的事件回调说明。

支付过程中的 loading 处理

Google Pay 原生按钮流程中有两段用户看不到进度的空档：

1. 点击按钮 → 浮层弹出：Google Pay 内部要做商户能力校验、加载资源，可能耗时数百毫秒到 1 秒。
2. 授权完成 → 拿到订单结果：浮层已关闭、页面回到你自己的 UI，SDK 正在调用 Legend 下单接口。该阶段在 Sandbox 环境实测耗时 20–40 秒，如果不给提示，用户会以为页面卡死。

SDK 通过 onPay 的三个中间态覆盖这两段空档：

const legend = new LegendBase({
  mode: "sandbox",
  onPay: (status, paymentData) => {
    switch (status) {
      case 'clicked':
        // 用户刚点下 Google Pay 按钮
        setLoading(true);
        disablePayButton();
        break;

      case 'authorizing':
        // 支付浮层即将弹起，会遮住页面，可选关闭 loading
        setLoading(false);
        break;

      case 'processing':
        // 已授权、正在下单 —— Sandbox 可能 20-40 秒
        setLoading(true, '正在处理支付，请稍候…');
        break;

      case 'success':
        setLoading(false);
        showSuccessPage(paymentData.data);
        break;

      case 'pending':
        setLoading(false);
        showPendingPage();
        break;

      case 'failed':
        setLoading(false);
        showErrorModal(paymentData.subject, paymentData.message);
        break;

      case 'cancelled':
        // 用户主动关闭了浮层 —— 不是错误，不要弹错误提示
        setLoading(false);
        showToast('支付已取消');
        enablePayButton();
        break;
    }
  },
  onError: (error) => {
    // 这里只包含真正的技术异常，用户主动取消已经走 onPay('cancelled')
    setLoading(false);
    showErrorModal(error.message);
  },
});

用户取消的识别