# Stripe Payment Element

通过一个安全可嵌入的 UI 组件，接受全球的支付方式。

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();` 进行确认。

Payment Element 是一款用于网页的用户界面组件，支持超过 100 种支付方式，具备输入验证与错误处理功能。您可以在网页应用前端中单独使用该组件，或与其他元素配合使用。

## 兼容的 API

Stripe 提供两个可与 Elements 兼容的核心支付 API。对于大多数集成场景，我们推荐使用 [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md)。

- 使用 [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) 来构建您的结账流程。Checkout Sessions 可覆盖与 PaymentIntent 类似的应用场景，包括使用 `price_data` 的基础支付，或包含行项目、税费、折扣、配送、订阅服务或 [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md)（该功能仅适用于 Checkout Sessions）的完整结账流程。

  使用 [Checkout Sessions API 构建结账页面](https://docs.stripe.com/payments/quickstart-checkout-sessions.md)。

- [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) 是一个仅建模支付步骤的底层 API。您需要传入最终金额，并自行构建所有结账逻辑，包括税费计算、折扣、配送、订阅和货币兑换。仅当您希望深度掌控结账状态并自行构建这些功能时，才应使用 PaymentIntent。

  [通过 Payment Intents API 从零开始构建定制化集成](https://docs.stripe.com/payments/advanced.md)。
 (See full diagram at https://docs.stripe.com/payments/payment-element)
[通过 Payment Element 和 Checkout Sessions 构建高级集成](https://docs.stripe.com/payments/quickstart-checkout-sessions.md): 使用 Checkout Sessions API 构建与 Payment Element 的集成应用。

[通过 Payment Element 和 PaymentIntent 构建集成](https://docs.stripe.com/payments/quickstart.md): 使用 Payment Intents API 构建您自己的结账流程。

[在 GitHub 上克隆一个示例应用程序](https://github.com/stripe-samples/accept-a-payment/tree/main/payment-element)

## 组合元素

Payment Element 与其他元素交互操作。例如，此表单使用一个附加元素来[自动填充结账详情](https://docs.stripe.com/payments/link.md)，使用另一个元素来[收集收货地址](https://docs.stripe.com/elements/address-element.md)。

> 您无法移除 Link 法律协议，因为该协议是确保用户充分了解服务条款和隐私政策的必要条件。[条款](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms)对象不适用于 Link 法律协议。

![ 包含联系信息、送货地址和支付字段的表单。联系信息标注为链接验证元素，送货地址标注为地址元素，支付字段标注为支付元素。](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.f60af275f69b6e6e73c766d1f9928457.png)
 结合多个元素的支付表单

有关此示例的完整代码，请参见[“将 Link 添加到 Elements 集成中”](https://docs.stripe.com/payments/link/add-link-elements-integration.md)。

还可以将 Payment Element 与 [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) 组合使用。这种情况下，Apple Pay 和 Google Pay 等钱包支付方式只会在 Express Checkout Element 中显示以避免重复。

## 支付方式

默认情况下，Stripe 会为您启用某些支付方式。我们可能还会在通知您后启用其他支付方式。您可以随时通过[管理平台](https://dashboard.stripe.com/settings/payment_methods)启用或禁用某些支付方式。通过 Payment Element，您可以使用[动态支付方式](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)来：

- 不使用代码，在[管理平台](https://dashboard.stripe.com/settings/payment_methods)中管理支付方式
- 根据位置、货币和交易金额等因素动态显示最相关的支付选项

例如，如果是德国客户，用欧元支付，他们会看到所有接受欧元的有效支付方式，最先列出的是德国广泛使用的支付方式。
![多种支付方式。](https://b.stripecdn.com/docs-statics-srv/assets/payment-element-methods.26cae03aff199d6f02b0d92bd324c219.png)

按照与客户相关的顺序显示支付方式

若要进一步自定义付款方式的显示方式，参见[自定义付款方式](https://docs.stripe.com/payments/customize-payment-methods.md)。若要添加非 Stripe 平台集成的付款方式，可以使用[自定义付款方式](https://docs.stripe.com/payments/payment-element/custom-payment-methods.md)。

如果您的集成要求您手动列出支付方式，请参阅[手动列出支付方式](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually)。

## 版面配置

您可以自定义 Payment Element 的布局来适应您的结账流程。下图是用不同的布局配置呈现的相同 Payment Element。
![三种结账表单示例。该图显示选项卡选项，其中客户从以选项卡方式显示的支付方式中进行选择，有时也会显示为两个折叠选项，其中支付方式垂直列出。您可以选择在折叠视图中显示或不显示单选按钮。 ](https://b.stripecdn.com/docs-statics-srv/assets/pe_layout_example.525f78bcb99b95e49be92e5dd34df439.png)

不同布局的 Payment Element。

#### 标签

选项卡布局使用选项卡水平显示支付方式。要使用此布局，请将 [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) 的值设置为 `tabs`。您还可以指定其他属性，例如 [layout.defaultCollapsed](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-defaultCollapsed)。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'tabs',
    defaultCollapsed: false,
  }
};
const elements = stripe.elements({ clientSecret, appearance }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

#### 有单选按钮的手风琴

手风琴式布局使用手风琴垂直显示支付方式。要使用此布局，请将 [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) 的值设置为 `accordion`。您还可以指定其他属性，例如 [layout.radios](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-radios)，以显示单选按钮。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: 'always',
    spacedAccordionItems: false
  }
};
const clientSecret = {{CLIENT_SECRET}}; // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。
const elements = stripe.elements({ clientSecret, appearance });
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

#### 没有单选按钮的手风琴

手风琴式布局使用手风琴垂直显示支付方式。要使用此布局，请将 [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) 的值设置为 `accordion`。您还可以指定其他属性，例如 [layout.spacedAccordionItems](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-spacedAccordionItems)，以获得额外的垂直空间。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: 'never',
    spacedAccordionItems: true
  }
};
const clientSecret = {{CLIENT_SECRET}}; // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。
const elements = stripe.elements({ clientSecret, appearance });
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

## 外观

使用 Appearance API 控制所有元素的样式。选择主题或更新具体详情。
![付款元素结账表单的亮暗模式示例。](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.png)

例如，选择“扁平”主题，并覆盖主文本颜色。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};
const options = { /* options */ };
const elements = stripe.elements({ clientSecret, appearance }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

参阅 [Appearance API](https://docs.stripe.com/elements/appearance-api.md) 文档，查看主题和变量的完整列表。

## 选项

Stripe Elements 支持的选项不止这些。例如，用 [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) 选项显示您的商家名称。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */};
const options = {
  business: { name: "RocketRides" }
};
const clientSecret = {{CLIENT_SECRET}}; // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。
const elements = stripe.elements(appearance, clientSecret);
const paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

Payment Element 支持以下选项。查看每个选项的参考条目，以了解更多信息。

|  |
|  |
| [布局](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout)                   | Payment Element 的布局。                           |
| [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) | 在 Payment Element 中显示的初始客户信息。                  |
| [商家](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business)                 | 在 Payment Element 中显示的有关您的业务的信息。               |
| [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | 支付方式的列出顺序。                                     |
| [字段](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields)                   | 是否显示特定字段。                                      |
| [readOnly](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-readOnly)           | 是否可修改支付详情。                                     |
| [条款](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms)                    | Payment Element 中是否显示授权或其他法律协议。默认行为是仅在必要时显示它们。 |
| [钱包](https://docs.stripe.com/js/elements_object/create_payment_element)                                                         | 是否显示 Apple Pay 或 Google Pay 等钱包。默认是尽可能显示它们。    |

## 错误

Payment Element 在客户端确认期间，自动为以下拒付代码显示面向客户的本地化错误信息：

- `card_declined`
- `card_velocity_exceeded`
- `expired_card`
- `fraudulent`
- `generic_decline`
- `incorrect_cvc`
- `incorrect_number`
- `incorrect_zip`
- `insufficient_funds`
- `invalid_cvc`
- `invalid_expiry_month`
- `invalid_expiry_year`
- `live_mode_test_card`
- `lost_card`
- `processing_error`
- `stolen_card`
- `test_mode_live_card`

要显示其他类型的错误的消息，请参阅[错误代码](https://docs.stripe.com/error-codes.md)和[错误处理](https://docs.stripe.com/error-handling.md)。