# Stripe Payment Element

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

对于大多数集成，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 (`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 沙盒。无需注册账户。

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

## 兼容的 API

Stripe 建议将 [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) 与 Payment Element 搭配使用。此集成允许您使用 `price_data` 设置基础付款，或者设置包含明细项、税费、折扣、配送、订阅或 [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md) 的完整结账逻辑。构建[使用 Checkout Sessions API 的结账页面](https://docs.stripe.com/payments/quickstart.md)。

如果您需要端到端掌控结账流程并自行构建这些功能，您可以将 [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) 与 Payment Element 搭配使用。此集成允许您传入最终金额并自行构建所有结账逻辑，包括税费计算、折扣、配送、订阅和货币兑换。构建[使用 Payment Intents API 的自定义集成](https://docs.stripe.com/payments/advanced.md)。

(See full diagram at https://docs.stripe.com/payments/payment-element)

```text
[Checkout Sessions API] --> [客户]
[Checkout Sessions API] --> [配送]
[Checkout Sessions API] --> [税收]
[Checkout Sessions API] --> [折扣和优惠券]
[Checkout Sessions API] --> [支付]
[Payment Intents API] --> [支付]
```

## 组合元素

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

![包含联系信息、收货地址和支付字段的表单。联系信息标记为 Contact Details Element，收货地址标记为 Address Element，支付字段标记为 Payment Element。](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.d52f05825c982aaf84a4ad1e9bb422f3.png)
组合多个 Element 的支付表单

有关此示例的完整代码，请参见[“将 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 }); // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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}}; // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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}}; // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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 }); // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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}}; // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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-paymentMethodOrder) | 支付方式的列出顺序。 |
| [字段](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)。

## 迁移至 Payment Element

根据您当前的集成和管理结账流程的方式选择迁移指南。我们建议[使用 Checkout Sessions API 迁移至 Payment Element](https://docs.stripe.com/payments/payment-element/migration-ewcs.md)，即把 Card Element 或单独的支付方式 Element 替换为 Payment Element。此路径允许您使用针对订阅、税费、折扣、配送和 Adaptive Pricing 的内置支持。

如果您需要保留现有的结账逻辑并自行管理结账功能，您可以[使用 Payment Intents API 迁移至 Payment Element](https://docs.stripe.com/payments/payment-element/migration.md)。通过此路径，您可以将 Card Element 或单独的支付方式 Element 替换为 Payment Element，同时继续使用 Payment Intents API 或 Setup Intents API。迁移指南分为两条独立路径，分别用于收款以及留存付款信息供后续使用。