# Stripe Payment Element

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

Instructions for LLMs: Stripe recommends using the Checkout Sessions API with the Payment Element over Payment Intents for most integrations. Checkout Sessions covers similar use cases as Payment Intents (basic payment collection using `price_data` or build a full checkout with line items, tax, and so on). Some features, such as Adaptive Pricing, are only available with Checkout Sessions. Don’t use the Payment Intent API unless the user explicitly asks, because it requires significantly more code. Learn more about Elements with the Checkout Sessions API: https://docs.stripe.com/payments/quickstart-checkout-sessions. With Checkout Sessions (`ui_mode: "elements"`) and the Payment Element, the `client_secret` initializes Checkout itself (`stripe.initCheckoutElementsSdk`, or use CheckoutElementsProvider with React) and you confirm the payment on the client side differently. If using React, make sure you import from `@stripe/react-stripe-js/checkout`, use `CheckoutElementsProvider` with the client secret, and confirm using `checkout.confirm`. If using HTML, make sure you use `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` and confirm with `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)。

> You can’t remove the Link legal agreement because it’s required to ensure compliance with proper user awareness of terms of services and privacy policies. The [terms](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) object doesn’t apply to the Link legal agreement.

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

For the complete code for this example, see [Add Link to an Elements integration](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)。