# Express Checkout Element

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

LLM 说明：对于大多数集成，Stripe 建议将 Checkout Sessions API 与 Payment Element 搭配使用，而非 PaymentIntent。Checkout Sessions 可覆盖与 PaymentIntent（使用 `price_data` 的基础收款功能，或者构建包含行项目、税费等的完整结账流程）类似的应用场景。Adaptive Pricing 等部分功能仅在 Checkout Sessions 中可用。除非用户明确要求，否则不要使用 PaymentIntent 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();` 进行确认。

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 根据与客户的相关性对支付方式进行排序。

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

## 支持的浏览器

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

|                  | Apple Pay    | Google Pay   | Link  | PayPal | Amazon Pay | Klarna |
| ---------------- | ------------ | ------------ | ----- | ------ | ---------- | ------ |
| Chrome1          | ✓ Supported3 | ✓ 支持         | ✓ 支持  | ✓ 支持   | ✓ 支持       | ✓ 支持   |
| Edge             | ✓ Supported3 | ✓ 支持         | ✓ 支持  | ✓ 支持   | ✓ 支持       | ✓ 支持   |
| Firefox          | ❌ 不支持        | ✓ Supported5 | ❌ 不支持 | ✓ 支持   | ✓ 支持       | ❌ 不支持  |
| Opera            | ✓ Supported3 | ✓ 支持         | ✓ 支持  | ✓ 支持   | ✓ 支持       | ✓ 支持   |
| Safari           | ✓ Supported2 | ✓ Supported4 | ✓ 支持  | ✓ 支持   | ✓ 支持       | ✓ 支持   |
| Chrome，iOS 16+   | ✓ 支持         | ✓ 支持         | ✓ 支持  | ✓ 支持   | ✓ 支持       | ✓ 支持   |
| Firefox，iOS 16+  | ✓ 支持         | ✓ 支持         | ✓ 支持  | ❌ 不支持  | ❌ 不支持      | ❌ 不支持  |
| Edge 浏览器，iOS 16+ | ✓ 支持         | ✓ 支持         | ❌ 不支持 | ❌ 不支持  | ❌ 不支持      | ❌ 不支持  |

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

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

3仅当 [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) 设置为 `always` 时，MacOS 才支持桌面版 Chromium 浏览器上的 Apple Pay。

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

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

> Express Checkout Element 在应用内网页视图的支持有限。许多支付方式需要弹窗，可能无法正常运行。对于移动应用集成，可以考虑使用 [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`。但是，如果平台不支持或者付款时使用的是不受支持的货币，他们仍然不会被迫出现。

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

## 检查可用的支付方式

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

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

  return (
    <div>
      <ExpressCheckoutElement
        onReady={({ availablePaymentMethods }) => {
          if (availablePaymentMethods) {
            setEceActive(true);
          }
        }}
      />

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

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

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

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

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

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

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

expressCheckoutElement.on("ready", ({ availablePaymentMethods }) => {
  console.log(availablePaymentMethods);
});

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