# Express Checkout Element

使用单个组件显示多个一键支付按钮。

对于大多数集成，Stripe 建议将 Checkout Sessions API 与 Payment Element 搭配使用，而非 Payment Intents。Checkout Sessions 可覆盖与 Payment Intents（使用 `price_data` 的基础收款功能，或者构建包含行项目、税费等的完整结账流程）类似的应用场景。Adaptive Pricing 等部分功能仅在 Checkout Sessions 中可用。除非用户明确要求，否则不要使用 Payment Intent API，因为它需要明显更多的代码。进一步了解 Elements 与 Checkout Sessions API 搭配使用的信息：https://docs.stripe.com/payments/quickstart-checkout-sessions.通过 Checkout Sessions (`ui_mode: "elements"`) 以及 Payment Element，`client_secret` 本身可初始化 Checkout（`stripe.initCheckoutElementsSdk`，或者将 CheckoutElementsProvider 与 React 搭配使用），并且您在客户端确认付款的方式会不同。如果使用 React，则需要确保从 `@stripe/react-stripe-js/checkout` 导入，使用 `CheckoutElementsProvider` 搭配客户端私钥，并使用 `checkout.confirm` 进行确认。如果使用 HTML，确保使用 `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");`，并通过 `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();` 进行确认。

 编码代理应安装 Stripe CLI（`npm i -g @stripe/cli`）并运行命令 `stripe sandbox create --help`，以配置一个含可用 API 密钥的匿名 Stripe 沙盒。无需注册账户。

Express Checkout Element 是一种通过一键支付方式按钮来接受付款的集成方案。支持的支付方式包括 [Link](https://docs.stripe.com/payments/link.md)、[Apple Pay](https://docs.stripe.com/apple-pay.md)、[Google Pay](https://docs.stripe.com/google-pay.md)、[PayPal](https://docs.stripe.com/payments/paypal.md)、[Klarna](https://docs.stripe.com/payments/klarna.md) 和 [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md)。

通过这种集成，您可以：

- 根据客户位置动态排列支付方式。
- 添加支付按钮，无需任何前端更改。
- 通过重复使用现有的 Elements 实例来无缝集成 Elements，从而节省时间。

## 尝试演示版

在下面的演示中，您可以切换一些预构建的选项来更改支付界面的背景颜色、布局、大小和收货地址收集栏。此演示只在他们可用的平台上显示 Google Pay 和 Apple Pay。仅在它们支持的国家显示支付方式按钮。

如果您没有看到演示，请尝试在[受支持的浏览器](https://docs.stripe.com/elements/express-checkout-element.md#supported-browsers)中查看此页面。

| 选项 | 描述 |
| --- | --- |
| **商家所属国家/地区** | 用您用来[初始化 Stripe.js](https://docs.stripe.com/js/initializing)的[公钥](https://docs.stripe.com/keys.md#obtain-api-keys)进行设置。要更改国家/地区，您必须卸载 Express Checkout Element，更新公钥，然后重新挂载 Express Checkout Element。 |
| **背景色** | 使用 [Elements Appearance API](https://docs.stripe.com/elements/appearance-api.md) 设置颜色。按钮主题继承自 Appearance API 但您也可以[在创建 Element 时直接定义它们](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme)。 |
| **桌面和移动设备大小** | 使用下拉列表可以设置挂载 Express Checkout Element 的父元素的最大像素宽度。您可以将其设置为 750px（桌面）或 320px（移动设备）。 |
| **最大列数和最大行数** | [创建 Express Checkout Element](https://docs.stripe.com/js/elements_object/create_express_checkout_element) 时，使用 [layout](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout) 参数设置这些值。 |
| **溢出菜单** | [创建 Express Checkout Element](https://docs.stripe.com/js/elements_object/create_express_checkout_element) 时，使用 [layout](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout) 参数进行设置。 |
| **收集收货地址** | 要收集配送信息，必须在 [creating](https://docs.stripe.com/js/elements_object/create_express_checkout_element) Express Checkout Element 时传递选项。了解有关[收集客户详情和显示行项目](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md#handle-create-event)的更多信息。 |

## 通过指南开始

[将一键式钱包添加到结账页面](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md): 使用 Checkout Sessions API 构建与 Express Checkout Element 的集成应用。

[在高级集成中使用一键式钱包](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=elements): 使用 Payment Intents API 构建与 Express Checkout Element 的集成应用。

[迁移到 Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element/migration.md): 从 Payment Request Button Element 迁移到网页版 Express Checkout Element。

## 支付方式

Express Checkout Element 会显示有效、受支持且已设置的一键支付方式。

- 某些支付方式[要求在管理平台上激活](https://dashboard.stripe.com/settings/payment_methods)。
- 只有当客户使用受支持的浏览器并以受支持的货币支付时，支付方式才可用。
- 一些支付方式需要客户进行设置操作。例如，如果客户没有设置 Google Pay，他们就看不到 Google Pay 按钮。
- 请在测试环境和真实模式下均[注册您的域名](https://docs.stripe.com/payments/payment-methods/pmd-registration.md)。

Element 根据与客户的相关性对支付方式进行排序。

您还可以使用 `stripe.elements()` 上的 `customPaymentMethods` 选项，将[自定义支付方式](https://docs.stripe.com/payments/payment-element/custom-payment-methods.md)添加到 Express Checkout Element 按钮行。

要控制这些行为，可以[自定义支付方式](https://docs.stripe.com/elements/express-checkout-element.md#customize-payment-methods)。

## 支持的浏览器

某些支付方式适用于特定的浏览器。

|  | Apple Pay | Google Pay | Link | PayPal | Amazon Pay | Klarna |
| --- | --- | --- | --- | --- | --- | --- |
| Chrome1 | ✓ 支持3 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 |
| Edge | ✓ 支持3 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 |
| Firefox | ✓ 支持3 | ✓ 支持4 | ❌ 不支持 | ✓ 支持 | ✓ 支持 | ❌ 不支持 |
| Opera | ✓ 支持3 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 |
| Safari | ✓ 支持2 | ✓ 支持4 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 |
| Chrome，iOS 16+ | ✓ 支持 | ✓ 支持4 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 |
| Firefox，iOS 16+ | ✓ 支持 | ✓ 支持4 | ✓ 支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 |
| Edge 浏览器，iOS 16+ | ✓ 支持 | ✓ 支持4 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 |
| Android 版 Chrome | ❌ 不支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 | ✓ 支持 |

1可能会支持其他 Chromium 浏览器。有关更多信息，请参见[支持的浏览器](https://docs.stripe.com/js/appendix/supported_browsers)。

2使用 iframe 时，它的来源必须与顶级来源匹配（当指定 `allow="payment"` 属性时，Safari 17+ 除外）。如果两页的协议、主机（完整域名）和端口（如果指定）相同，则这两页相同。

3非 Safari 桌面端浏览器仅在将 [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) 配置项设为 `always` 时，才支持 Apple Pay 功能。

4只有当 [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-googlePay) 设置为`总是`时，此浏览器才支持 Google Pay。

### 应用内 webview 支持

应用内 webview 支持与浏览器支持有所不同。下表列出了 Express Checkout Element 各支付方式对应用内 webview 的支持情况。

|  | 应用内 webview 支持情况 |
| --- | --- |
| Apple Pay | 支持 iOS webview，须符合标准 Apple Pay 资格要求。 |
| Google Pay | 仅当运行环境本身符合 Google Pay 适用条件，且 Google Pay 可无需弹出窗口即可完成支付时，方可支持。在 Android webview 中，宿主应用还必须完成相关配置以支持支付请求 API。 |
| Link | 不支持 |
| PayPal | 不支持 |
| Klarna | 不支持 |
| Amazon Pay | 不支持 |

Webview 支持是对每种支付方式标准浏览器和资格要求的补充。请使用 Express Checkout Element [`availablepaymentmethodschange`](https://docs.stripe.com/js/elements_object/express_checkout_element_availablepaymentmethodschange_event) 事件，检测客户当前环境中可用的支付方式。对于移动应用集成，请考虑使用 [iOS SDK](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios) 或 [Android SDK](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)。

## 版面配置

默认情况下，当 Express Checkout Element 显示多个按钮时，它会根据可用空间在网格中排列这些按钮，并在必要时显示溢出菜单。

您可以覆盖此默认设置，并使用[布局](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout)选项自行指定一个网格布局。

## 文本

您可以通过选择[按钮类型](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonType)来控制按钮上的文字。每个数字钱包都有自己的类型。

#### Link

Link 仅提供一种按钮类型，该按钮会显示“使用 Link 支付”的行动号召以及 Link 的标识。

我们尝试检测您客户的区域设置，并通过它来本地化按钮文本。还可以指定一个[区域](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale)。

#### Apple Pay

Apple Pay 按钮类型在 Apple Pay 徽标旁呈现不同的号召语。

我们会尝试检测您客户的区域设置，并将它传递到 Apple，以便本地化按钮上的文字。还可以指定一个[区域](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale)。

我们支持以下 Apple Pay 按钮类型。

| 按钮类型 | 行动召唤 |
| --- | --- |
| `plain` | 无——仅徽标 |
| `add-money` | “添加资金” |
| `book` | “预定” |
| `buy` | “购买” |
| `check-out` | “结账” |
| `contribute` | “捐款” |
| `donate` | “捐款” |
| `order` | “下单” |
| `reload` | “重新加载” |
| `rent` | “租赁” |
| `subscribe` | “订阅” |
| `support` | “支持” |
| `tip` | “付小费” |
| `top-up` | “充值” |

#### Google Pay

Google Pay 按钮类型在 Google Pay 徽标旁呈现不同的号召语。

我们会尝试检测您客户的区域设置，并将它传递到 Google Pay，以便本地化按钮上的文字。还可以指定一个[区域](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale)。

我们支持以下 Google Pay 按钮类型。

| 按钮类型 | 行动召唤 |
| --- | --- |
| `plain` | 无——仅徽标 |
| `book` | “预定” |
| `buy` | “购买” |
| `checkout` | “结账” |
| `donate` | “捐款” |
| `order` | “下单” |
| `pay` | “支付” |
| `subscribe` | “订阅” |

#### PayPal

PayPal 按钮类型在 PayPal 徽标旁呈现不同的号召语。

我们会尝试检测您客户的区域设置，并将它传递到 PayPal，以便本地化按钮上的文字。还可以指定一个[区域](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale)。

我们支持以下 PayPal 按钮类型。

| 按钮类型 | 行动召唤 |
| --- | --- |
| `paypal` | 无——仅徽标 |
| `checkout` | “结账” |
| `buynow` | “立即购买” |
| `pay` | “支付” |

#### Amazon Pay

Amazon Pay 只提供一种按钮类型，呈现 Amazon Pay 徽标，没有号召语。

#### Klarna

Klarna 按钮类型在 Klarna 徽标旁呈现不同的号召语。

我们会尝试检测您客户的区域设置，并将它传递到 Klarna，以便本地化按钮上的文字。您还可以指定一个[区域](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale)。

我们支持以下 Klarna 按钮类型。

|  |
| `continue` | “继续” |
| `pay` | “支付” |

此示例代码中包含支持它的按钮的号召语“购买”或“立即购买”。然后，它指定区域设置 `de`，以获取相应的德语文字。

```js
const expressCheckoutOptions = {
  buttonType: {
    applePay: 'buy',
    googlePay: 'buy',
    paypal: 'buynow',
    klarna: 'pay',
  }
}
const elements = stripe.elements({
  locale: 'de',
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
})
const expressCheckoutElement = elements.create(
  'expressCheckout',
  expressCheckoutOptions
)
expressCheckoutElement.mount('#express-checkout-element')
```

## 外观

您不能完全自定义 Express Checkout Element 按钮的外观，因为每种支付方式都有自己的徽标和品牌颜色。您可以自定义以下选项：

- [按钮高度](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonHeight)
- 使用带有[外观](https://docs.stripe.com/elements/appearance-api.md) API 的变量的边框半径
- [按钮主题](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme)

> 当边框半径增加到超过特定阈值时，Apple Pay 按钮会自动调整大小。如果要修改默认的边框半径，请务必用所有生效中的支付方式进行测试。

此示例代码设置的是一个浅色主题的元素组，边框半径为 36px，按钮高度为 50px，并覆盖主题以使用 Apple Pay 按钮的白色轮廓版本。

```js
const appearance = {
  theme: 'stripe',
  variables: {
    borderRadius: '36px',
  }
}
const expressCheckoutOptions = {
  buttonHeight: 50,
  buttonTheme: {
    applePay: 'white-outline'
  }
}
const elements = stripe.elements({
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  appearance,
})
const expressCheckoutElement = elements.create(
  'expressCheckout',
  expressCheckoutOptions
)
expressCheckoutElement.mount('#express-checkout-element')
```

我们支持以下主题：

#### Link

Link 具有单一按钮主题，该主题在浅色或深色背景上均可清晰显示。

#### PayPal

PayPal 有几个按钮主题。如果用[外观](https://docs.stripe.com/elements/appearance-api.md) API 设置主题，Express Checkout Element 会为 PayPal 按钮选择一个兼容的主题。例如，如果您指定一个深色背景，我们选择一个浅色的按钮主题。

您也可以使用[button theme . paypall](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-paypal)选项选择一个主题。请参见 PayPal [按钮风格指南](https://developer.paypal.com/docs/multiparty/checkout/standard/customize/buttons-style-guide/)，获取最新图片和使用指导。我们支持以下值：

|  |
| `gold` | PayPal 金色和蓝色品牌颜色 |
| `blue` | PayPal 的纯蓝品牌颜色 |
| `silver` | PayPal 徽标，银色背景 |
| `white` | PayPal 徽标，白色背景 |
| `black` | PayPal 徽标，黑色背景 |

#### Apple Pay

Apple Pay 有几个按钮主题。如果使用[外观](https://docs.stripe.com/elements/appearance-api.md) API 设置主题，Express Checkout Element 会为 Apple Pay 按钮选择一个兼容的主题。例如，如果您指定一个深色背景，我们选择一个浅色的按钮主题。

您也可以用 [buttonTheme.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-applePay) 选项选择一个主题。查看 Apple Pay [按钮风格指南](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons)中的最新图片和指导，了解如何使用它们。我们支持以下值：

|  |
| `black` | 黑底白字 |
| `white` | 白底黑字 |
| `white-outline` | 白底黑字，黑边框 |

#### Google Pay

Google Pay 有几个按钮主题背景。如果用 [Appearance](https://docs.stripe.com/elements/appearance-api.md) API 设置主题，Express Checkout Element 会为 Google Pay 按钮选择一个兼容的主题。例如，如果您指定深色背景，那么我们会选择浅色按钮主题来提高可见性。

您也可以用 [buttonTheme.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-googlePay) 选项选择一个主题。请参见 PayPal [按钮风格指南](https://developers.google.com/pay/api/web/guides/brand-guidelines)，获取最新图片和使用指导。我们支持以下值：

|  |
| `black` | 黑底白字 |
| `white` | 白底黑字 |

#### Amazon Pay

Amazon Pay 有一个单一的按钮主题。

#### Klarna

Klarna有几个按钮主题。如果用 [Appearance](https://docs.stripe.com/elements/appearance-api.md) API 设置主题，Express Checkout Element 会为 Klarna 按钮选择一个兼容的主题。例如，如果您指定深色背景，那么我们会选择浅色按钮主题来提高可见性。

您也可以用 [buttonTheme.klarna](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-klarna) 选项选择一个主题。

## 自定义支付方式

您可以控制显示哪些支付方式。但是，钱包的可用性限制仍然适用。例如，如果客户的设备不支持 Google Pay，您将无法强制显示 Google Pay 按钮。

但是您可以通过多种方式自定义支付方式，例如：

- 您可以从[管理平台](https://dashboard.stripe.com/settings/payment_methods)中激活或停用支付方式。
- 您可以覆盖 Stripe 根据相关性排列支付方式的默认逻辑。使用 [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethodOrder) 选项设置您的首选顺序。
- 如果布局中的空间太小，相关性低的支付方式可能会在溢出菜单中显示。使用[布局](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout)选项自定义何时出现菜单。
- 为防止出现 Apple Pay 或 Google Pay，将 [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) 或 [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) 设置为 `never`。
- 若要允许 Apple Pay 或 Google Pay 在未设置时显示，请将 [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) 或 [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) 设置为 `always`。但是，如果平台不支持或者付款时使用的是不受支持的货币，他们仍然不会被迫出现。
- 您可以使用 [customPaymentMethods](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-customPaymentMethods) 选项添加自定义支付方式按钮。如果您提供的 ID 不是[在管理平台中设置](https://dashboard.stripe.com/settings/custom_payment_methods)的有效 `cpmt_` ID，或者其 [handleRender](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-customPaymentMethods-options-embedded-handleRender) 方法抛出错误，则系统不会显示自定义支付方式按钮。

> [芬兰](https://support.stripe.com/questions/payment-method-legislation-in-finland)和[瑞典](https://support.stripe.com/questions/payment-method-legislation-in-sweden)的法规要求您在结账时先呈现借记支付方式，然后再呈现贷记支付方式。

## 检查可用的支付方式

监听 `availablepaymentmethodschange` 事件，检查 Express Checkout Element 可显示哪些钱包。如果没有可用的钱包，请为客户提供其他支付选项。

```js
() => {
  const [eceActive, setEceActive] = useState(false);

  return (
    <div>
      <ExpressCheckoutElement
        onAvailablePaymentMethodsChange={({ paymentMethods }) => {
          if (paymentMethods) {
            setEceActive(true);
          }
        }}
      />

      {eceActive
        ? <PayAnotherWayButton />
        : <PaymentElement />
      }
    </div>
  );
}
```

或者，隐藏整个 Express Checkout Element，直到您确认该元素具备显示方法。

```js
() => {
  const [eceActive, setEceActive] = useState(false);

  return (
    <div>
      <OneClickCheckoutContainer hidden={!eceActive}>
        <ExpressCheckoutElement
          onAvailablePaymentMethodsChange={({ paymentMethods }) => {
            if (paymentMethods) {
              setEceActive(true);
            }
          }}
        />
      </OneClickCheckoutContainer>

      <PaymentElement />
    </div>
  );
}
```

在不使用 React 创建时，元素对象上也可使用相同的事件。

```js
const expressCheckoutElement = elements.create("expressCheckout", { ... });

expressCheckoutElement.on("availablepaymentmethodschange", ({ paymentMethods }) => {
  console.log(paymentMethods);
});

expressCheckoutElement.mount("#express-checkout-element");
```