# 构建包含 Link 的自定义结账页面

用 Payment Element 或 Link Authentication Element 集成 Link。

如果您的 Connect 平台使用[客户配置账户](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer)，请参阅我们的[指南](https://docs.stripe.com/connect/use-accounts-as-customers.md)，将代码中对 `Customer` 和事件的引用替换为相应的 Accounts v2 API 参考文件。

本指南将逐步介绍如何使用 [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) 并结合 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 或 [Link Authentication Element](https://docs.stripe.com/payments/elements/link-authentication-element.md) 来通过 [Link](https://docs.stripe.com/payments/link.md) 接受付款。

您可以通过以下三种方式获取客户邮箱地址，用于 Link 身份验证和注册：

- \**传递电子邮件地址：**您可以使用 [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) 向 Payment Element 传递电子邮件地址。如果您已经在结账流程中收集了客户的邮件地址和/或电话号码，则我们建议采用这种方法。
- \**收集电子邮件地址：**您可以直接在 Payment Element 中收集电子邮件地址。如果您在结账流程中的任何环节都未收集电子邮件地址，我们建议使用这种方法。
- \**Link 身份验证 Element：**您可以使用 Link 身份验证 Element 创建一个用于邮箱收集和 Link 身份验证的统一邮箱输入字段。如果您使用 [Address Element](https://docs.stripe.com/elements/address-element.md)，我们建议采用此方式。
![在结账过程中直接在 Payment Element 中通过 Link 进行验证或注册](https://b.stripecdn.com/docs-statics-srv/assets/link-in-pe.2efb5138a4708b781b8a913ebddd9aba.png)

收集客户邮箱地址，用于 Link 身份验证或注册

## 设置 Stripe [服务器端]

首先，[创建 Stripe 账户](https://dashboard.stripe.com/register)或[登录](https://dashboard.stripe.com/login)。

用我们的官方库从您的应用程序访问 Stripe API：

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

## 创建 PaymentIntent [服务器端]

Stripe 使用一个 [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 对象来表示您向客户收款的意图，跟踪整个过程中的收费尝试和付款状态变化。
![整个支付流程概览](https://b.stripecdn.com/docs-statics-srv/assets/accept-a-payment-payment-element.5cf6795a02f864923f9953611493d735.svg)

如果您收集银行卡信息以[通过 Setup Intents 供未来使用](https://docs.stripe.com/payments/save-and-reuse.md)，请手动列出支付方式，而不是使用动态支付方式。如需使用未启用动态支付方式的 Link，请更新您的集成，以将 `link` 传递至 `payment_method_types`。

创建 PaymentIntent 时，通过动态支付方式，[动态地向客户提供最相关的支付方式](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)，包括 Link。如需使用动态支付方式，请不要包含 `payment_method_types` 参数。另外，您还可以选择启用 `automatic_payment_methods`。

> 当您的集成未设置 `payment_method_types` 参数时，某些支付方式会自动开启，包括银行卡和钱包。

如需使用动态支付方式将 Link 添加到您的 Elements 集成中：

1. 在管理平台的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)中开启 Link。
1. 如果您的现有集成可手动列出支付方式，请从您的集成中删除 [payment_method_types](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-payment_method_types)参数。

### 检索客户端私钥

PaymentIntent 中包含的是一个*客户端私钥* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer))，用于在客户端安全地完成支付流程。有不同的方法可以将客户端私钥传递到客户端。

#### 单页应用

使用浏览器的 `fetch` 功能，从您的服务器上的端点获取客户端私钥。如果您的客户端是单页应用，特别是用现代的前端框架（例如 React）搭建的情况，则该方法最为合适。创建服务于客户端私钥的服务器端点：

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

然后在客户端用 JavaScript 获取客户端私钥：

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### 服务端呈现

从服务器将客户端私钥传递到客户端。如果在将静态内容发送到浏览器之前，您的应用程序会在服务器上生成静态内容，则此种方法最有效。

在您的结账表单中添加 [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。在您的服务器代码中，从 PaymentIntent 检索客户端密钥：

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <div id="payment-element">
    <!-- placeholder for Elements -->
  </div>
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

## 收集客户电子邮件地址

Link 通过使用客户的邮箱地址来进行身份验证。根据您的结账流程，您有以下几种选择：将邮箱地址传递给 Payment Element、在 Payment Element 内直接收集，或使用 Link 身份验证 Element。其中，Stripe 建议在可用的情况下将客户邮箱地址传递给 Payment Element。

#### 传入电子邮件

如果您满足以下_任一_条件：

- 在客户到达支付页面之前，您就已经知道其电子邮件地址（例如，从客户资料中）。
- 您不需要从客户那里收集收货地址。
- 您更偏向于使用您自己的位于支付表单之前的电子邮件输入字段。

然后，通过将客户邮箱传递给 Payment Element 来集成 Link，这可以在客户进入支付步骤时立即触发 Link 身份验证流程，从而实现更快速的结账。该选项只需集成一个元素，即 Payment Element。
![未注册用户在 Payment Element 中使用 Link 的预览](https://b.stripecdn.com/docs-statics-srv/assets/lape-unregistered-user.293e19b8cc97c58e2c7dc22f8ef8f75b.png)

Link 会在结账表单中自动填写已收集的邮箱地址，以实现更快速的结账
![已注册用户在 Payment Element 中使用 Link 的预览](https://b.stripecdn.com/docs-statics-srv/assets/collect-email-before-returning-user.d6dee1a891e3068b1c1892edefa9c01f.png)

Link 会为现有客户提供身份验证提示

在此流程中，您在客户进入支付步骤之_前_通过自己的表单字段收集邮箱地址，然后将该邮箱传递给 Payment Element。Payment Element 会在支付步骤对客户进行身份验证，随后显示客户在其 Link 账户中保存的支付详情，或者在客户输入银行卡信息后显示 Link 账户创建表单。流程如下所示：
使用 Link Authentication Element 集成 Link (See full diagram at https://docs.stripe.com/payments/link/add-link-elements-integration)
此集成选项不收集客户的收货地址。如果您需要收集收货地址，请通过使用 Link 身份验证 Element、Address Element 和 Payment Element 来集成 Link。

#### 收集电子邮件

Payment Element 中的 Link 身份验证功能允许您的客户直接在 Payment Element 中输入邮箱地址，无需额外的集成工作。

在此流程中，您的客户在结账时直接在 Payment Element 中输入邮箱地址，并进行 Link 的身份验证或注册。如果客户尚未注册 Link，且在 Payment Element 中选择了一种支持的支付方式，系统会提示他们使用 Link 保存其支付详情。对于已注册的客户，Link 会自动填充其支付信息。

#### 使用 Link Authentication Element

如果您满足以下_任一_条件：

- 您希望使用一个单一、优化的组件来同时完成邮箱收集和 Link 身份验证。
- 您需要从客户那里收集收货地址。

然后，请使用实施这些元素的集成流程：Link 身份验证 Element、Payment Element 以及可选的 Address Element。

启用 Link 的结账页面在开头放置了 Link 身份验证 Element，随后是 Address Element，最后是 Payment Element。对于多页结账流程，您也可以按照相同的顺序将 Link 身份验证 Element 分布在不同的页面上。
![使用多个元素创建支付表单](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.f60af275f69b6e6e73c766d1f9928457.png)

使用多个元素创建支付表单

集成的工作方式如下：
该图表描述了用 Link Authentication Element 集成 Link 的方式 (See full diagram at https://docs.stripe.com/payments/link/add-link-elements-integration)
## 设置您的支付表单 [客户端]

现在，您可以用 Elements 预构建的 UI 组件设置您的自定义支付表单了。支付页面上的地址也必须以 `https://` 开头，不能是 `http://`，否则您的集成不能工作。您可以在不使用 HTTPS 的情况下测试您的集成。准备好进行真实收款时[启用 HTTPS](https://docs.stripe.com/security/guide.md#tls)。

#### 传入电子邮件

Payment Element 会呈现一个预填的客户联系表单，其中包括电话号码和电子邮件地址。它还会呈现一个动态表单，允许客户选择支付方式类型。该表单会自动收集客户所选支付方式类型的所有必要支付详细信息。

此外，Payment Element 还负责显示已认证客户的Link保存支付方式。

#### React

### 设置 Stripe Elements

从 npm 公共注册表安装 [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) 和 [Stripe.js 加载器](https://www.npmjs.com/package/@stripe/stripe-js)：

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

### 构建支付表单

在您的支付页面，用 `Elements` 组件包住您的支付表单，传递 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。

如果您有其他客户信息，请将其传递到 `PaymentElement` 的 `defaultValues.billingDetails` 对象中。尽可能预先填写更多信息，可以简化客户创建和重复使用 Link 账户的流程。您还可以传递[外观对象](https://docs.stripe.com/js/elements_object/update#elements_update-options-appearance)，自定义 Elements 以匹配您网站的设计。

然后，在您的支付表单中渲染 `PaymentElement`。我们建议至少将客户的电子邮箱地址传递到 [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) 中，以便为 Link 预先填写客户数据。

```jsx
import {loadStripe} from "@stripe/stripe-js";
import {
  Elements,
  PaymentElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

// Customize the appearance of Elements using the Appearance API.
const appearance = {/* ... */};

const CheckoutPage = ({clientSecret}) => (
  <Elements stripe={stripe} options={{clientSecret, appearance}}>
    <CheckoutForm />
  </Elements>
);

export default function CheckoutForm() {
  return (
    <form>
      <h3>Payment</h3>

      // Prefill customer data using the defaultValues option. Passing in the email
      // is required for this integration. The other fields are optional.
      <PaymentElement
        options={{
          defaultValues: {
            billingDetails: {
              email: 'foo@bar.com',
              name: 'John Doe',
              phone: '888-888-8888',
            }
          }
        }}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

#### HTML + JS

### 设置 Stripe Elements

在您的支付页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 `head` 部分。始终直接从 js.stripe.com 加载 Stripe.js 以保持 PCI 合规。请勿将脚本包含在捆绑包中，也不要自己托管其副本。

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

创建一个 [Stripe 对象](https://docs.stripe.com/js.md#stripe-function)实例，提供您可公开的 [API 密钥](https://docs.stripe.com/keys.md)作为第一个参数：

```javascript
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

### 在您的支付页面添加 Link Elements

在您的支付页面，用唯一 ID 创建空的 DOM 节点，让 Elements 呈现到这里：

```html
<form id="payment-form">
  <h3>Payment</h3>
  <div id="payment-element"></div>

  <button id="submit">Submit</button>
</form>
```

在您加载刚配置好的表单时，创建一个新的 Elements 组，传递 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。您还可以传入[外观对象](https://docs.stripe.com/js/elements_object/update#elements_update-options-appearance)，自定义 Elements，使其匹配您网站的设计。

如果您有其他客户信息，请将其传递给 `PaymentElement` 的 `defaultValues.billingDetails` 对象。尽可能多地预填信息可以简化客户创建和重复使用 Link 账户的流程。

最后，创建每个 Element 的实例，并将其挂在到它们对应的 DOM 节点：

```javascript
// Customize the appearance of Elements using the Appearance API.
const appearance = { /* ... */ };

// Create an elements group from the Stripe instance passing in the clientSecret and, optionally, appearance.
const elements = stripe.elements({clientSecret, appearance});

// Prefill customer data using the defaultValues option. Passing in the email
// is required for this integration. The other fields are optional.
const paymentElement = elements.create('payment', {
  defaultValues: {
    billingDetails: {
      email: 'foo@bar.com',
      name: 'John Doe',
      phone: '888-888-8888',
    },
  },
});

// Mount the Elements to their corresponding DOM node
paymentElement.mount("#payment-element");
```

#### 收集电子邮件

Payment Element 会呈现一个预填的客户联系表单，其中包括电话号码和电子邮件地址。它还会呈现一个动态表单，允许客户选择支付方式类型。该表单会自动收集客户所选支付方式类型的所有必要支付详细信息。

此外，Payment Element 还会处理已认证客户所-保存的 Link 支付方式的显示。对于这种集成方式，您必须在[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)中保持 Link 处于启用状态。

#### React

### 设置 Stripe Elements

从 npm 公共注册表安装 [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) 和 [Stripe.js 加载器](https://www.npmjs.com/package/@stripe/stripe-js)：

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

### 构建支付表单

在您的支付页面，用 `Elements` 组件包住您的支付表单，传递 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。

如果您有其他客户信息，请将其传递到 `PaymentElement` 的 `defaultValues.billingDetails` 对象中。尽可能预先填写更多信息，可以简化客户创建和重复使用 Link 账户的流程。您还可以传递[外观对象](https://docs.stripe.com/js/elements_object/update#elements_update-options-appearance)，自定义 Elements 以匹配您网站的设计。

然后，在您的支付表单中渲染 `PaymentElement`。我们建议至少将客户的电子邮箱地址传递到 [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) 中，以便为 Link 预先填写客户数据。

```jsx
import {loadStripe} from "@stripe/stripe-js";
import {
  Elements,
  PaymentElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

// Customize the appearance of Elements using the Appearance API.
const appearance = {/* ... */};

const CheckoutPage = ({clientSecret}) => (
  <Elements stripe={stripe} options={{clientSecret, appearance}}>
    <CheckoutForm />
  </Elements>
);

export default function CheckoutForm() {
  return (
    <form>
      <h3>Payment</h3>

      // Create the Payment Element
      <PaymentElement/>
      <button type="submit">Submit</button>
    </form>
  );
}
```

#### HTML + JS

### 设置 Stripe Elements

在您的支付页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 `head` 部分。始终直接从 js.stripe.com 加载 Stripe.js 以保持 PCI 合规。请勿将脚本包含在捆绑包中，也不要自己托管其副本。

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

创建一个 [Stripe 对象](https://docs.stripe.com/js.md#stripe-function)实例，提供您可公开的 [API 密钥](https://docs.stripe.com/keys.md)作为第一个参数：

```javascript
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

### 在您的支付页面添加 Link Elements

在您的支付页面，用唯一 ID 创建空的 DOM 节点，让 Elements 呈现到这里：

```html
<form id="payment-form">
  <h3>Payment</h3>
  <div id="payment-element"></div>

  <button id="submit">Submit</button>
</form>
```

在您加载刚配置好的表单时，创建一个新的 Elements 组，传递 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。您还可以传入[外观对象](https://docs.stripe.com/js/elements_object/update#elements_update-options-appearance)，自定义 Elements，使其匹配您网站的设计。

如果您有其他客户信息，请将其传递给 `PaymentElement` 的 `defaultValues.billingDetails` 对象。尽可能多地预填信息可以简化客户创建和重复使用 Link 账户的流程。

最后，创建每个 Element 的实例，并将其挂在到它们对应的 DOM 节点：

```javascript
// Customize the appearance of Elements using the Appearance API.
const appearance = { /* ... */ };

// Create an elements group from the Stripe instance passing in the clientSecret and, optionally, appearance.
const elements = stripe.elements({clientSecret, appearance});

// Create the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);

// Mount the Elements to their corresponding DOM node
paymentElement.mount("#payment-element");
```

#### 使用 Link Authentication Element

Link 身份验证 Element 会渲染一个邮箱地址输入框。当 Link 将客户邮箱与现有的 Link 账户匹配时，会向客户的手机发送一个安全的一次性验证码进行身份验证。如果客户成功通过验证，Stripe 会自动显示他们在 Link 中保存的地址和支付方式，供客户使用。

这种集成方式还会创建 Payment Element，它会渲染一个动态表单，允许您的客户选择支付方式类型。该表单会自动收集客户所选支付方式类型所需的所有支付详情。对于已通过身份验证的客户，Payment Element 还会处理 Link 中已保存支付方式的显示。

#### React

### 设置 Stripe Elements

从 npm 公共注册表安装 [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) 和 [Stripe.js 加载器](https://www.npmjs.com/package/@stripe/stripe-js)。

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

在您的支付页面，用 `Elements` 组件包住您的支付表单，传递[上一步](https://docs.stripe.com/payments/link/add-link-elements-integration.md#web-create-intent)中的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。如果您已经在表单的另一部分收集了客户的邮件地址，请将您当前输入的内容替换为 `linkAuthenticationElement​`。

如果您不收集邮箱地址，请在结账流程中添加 `linkAuthenticationElement​`。您必须将 `linkAuthenticationElement` 放置在 `ShippingAddressElement`（如果您收集收货地址则为可选）和 `PaymentElement` 之前，以便 Link 能够在 `ShippingAddressElement` 和 `PaymentElement` 中自动填写客户在 Link 中保存的信息。您还可以传入 [外观选项](https://docs.stripe.com/elements/appearance-api.md)，自定义 Elements 以匹配您网站的设计。

如果您有客户的邮箱地址，请将其传递给 `linkAuthenticationElement` 的 `defaultValues` 选项。这将预填客户的邮箱地址并启动 Link 身份验证流程。

如果您有其他客户信息，请将其传递给 `PaymentElement` 的 `defaultValues.billingDetails` 对象。尽可能多地预填信息可以简化客户创建和使用 Link 账户的流程。

然后，在支付表单中呈现 `linkAuthenticationElement` 和 `PaymentElement` 组件：

```jsx
import {loadStripe} from "@stripe/stripe-js";
import {
  Elements,
  LinkAuthenticationElement,
  PaymentElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

// Customize the appearance of Elements using the Appearance API.
const appearance = {/* ... */};

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

const CheckoutPage = ({clientSecret}) => (
  <Elements stripe={stripe} options={{clientSecret, appearance, loader}}>
    <CheckoutForm />
  </Elements>
);

export default function CheckoutForm() {
  return (
    <form>
      <h3>Contact info</h3>
      <linkAuthenticationElement
        // Optional prop for prefilling customer information
        options={{
          defaultValues: {
            email: 'foo@bar.com',
          },
        }}
      />
      <h3>Payment</h3>
      <PaymentElement
        // Optional prop for prefilling customer information
        options={{
          defaultValues: {
            billingDetails: {
              name: 'John Doe',
              phone: '888-888-8888',
            },
          },
        }}
      />;
      <button type="submit">Submit</button>
    </form>
  );
}
```

`linkAuthenticationElement`、`PaymentElement` 和 `ShippingAddressElement` 不需要位于同一页面。如果您在结账流程中分步骤向客户展示联系信息、收货信息和支付详情，则可以将每个 Element 放置在相应的步骤或页面中。在联系信息收集步骤中包含 `linkAuthenticationElement` 作为邮箱输入表单，以确保客户能够充分利用 Link 提供的收货和支付自动填写功能。

如果您在结账流程早期通过 Link 身份验证 Element 收集了客户的邮箱地址，则无需在收货页面或支付页面再次显示该元素。

### 检索电子邮件地址

您可以使用 `linkAuthenticationElement` 组件上的 `onChange` 属性检索电子邮件地址详细信息。每当用户更新电子邮件字段或自动填充已保存的客户电子邮件时，`onChange` 处理程序就会触发。

```jsx
<linkAuthenticationElement onChange={(event) => {
  setEmail(event.value.email);
}} />
```

### 预填客户电子邮件地址

Link 身份验证 Element 接受邮箱地址。通过 `defaultValues` 选项提供客户的邮箱地址，可在客户进入支付页面后立即触发 Link 身份验证流程。

```jsx
<linkAuthenticationElement options={{defaultValues: {email: 'foo@bar.com'}}}/>
```

#### HTML + JS

### 设置 Stripe Elements

在您的支付页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 `head` 部分。始终直接从 js.stripe.com 加载 Stripe.js 以保持 PCI 合规。请勿将脚本包含在捆绑包中，也不要自己托管其副本。

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

创建一个 [Stripe 对象](https://docs.stripe.com/js.md#stripe-function)实例，提供您可公开的 [API 密钥](https://docs.stripe.com/keys.md)作为第一个参数：

```javascript
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

### 将 Link Elements 添加到您的支付页面

在您的支付页面，用唯一 ID 创建空的 DOM 节点，让 Elements 呈现到这里：

```html
<form id="payment-form">
  <h3>Contact info</h3>
  <div id="link-authentication-element"></div>

  <h3>Payment</h3>
  <div id="payment-element"></div>

  <button id="submit">Submit</button>
</form>
```

在您加载刚配置好的表单时，创建一个新的 Elements 组，并传入[客户端私钥](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。如果您已经在支付表单中收集了客户的邮件地址，则将当前输入替换为 `linkAuthenticationElement`。

如果您不收集邮箱地址，请在结账流程中的`shippingAddress`（如果您收集收货地址则为可选）之前添加`linkAuthenticationElement`。添加`PaymentElement`，以便 Link 能够在`shippingAddress`和`PaymentElement`中自动填写客户在 Link 中保存的信息。您还可以传入[外观配置对象](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance)，自定义 Elements 以匹配您网站的设计。

如果您有客户的邮箱地址，请将其传递给 `linkAuthenticationElement` 的 `defaultValues` 选项。这将预填客户的邮箱并启动 Link 身份验证流程。如果您有其他客户信息，请将其传递给 `PaymentElement` 的 `defaultValues.billingDetails` 对象。尽可能多地预填信息可以简化客户创建和重复使用 Link 账户的流程。

最后，创建每个 Element 的实例，并将其挂在到它们对应的 DOM 节点：

```javascript
// Customize the appearance of Elements using the Appearance API.
const appearance = { /* ... */ };

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

// Create an elements group from the Stripe instance, passing the clientSecret (obtained in step 2), loader, and appearance (optional).
const elements = stripe.elements({clientSecret, appearance, loader});

// Create Element instances
const linkAuthenticationElement = elements.create("linkAuthentication");
// Passing in defaultValues is optional, but useful if you want to prefill consumer information to
// ease consumer experience.
const paymentElement = elements.create('payment', {
  defaultValues: {
    billingDetails: {
      name: 'John Doe',
      phone: '888-888-8888',
    },
  },
});

// Mount the Elements to their corresponding DOM node
linkAuthenticationElement.mount("#link-authentication-element");
paymentElement.mount("#payment-element");
```

`linkAuthenticationElement` 会渲染一个邮箱地址输入框。当 Link 将客户邮箱与现有的 Link 账户匹配时，会向客户的手机发送一个安全的一次性验证码进行身份验证。如果客户成功通过验证，Stripe 会自动显示他们在 Link 中保存的地址和支付方式，以便客户使用。

`PaymentElement` 会渲染一个动态表单，允许您的客户选择支付方式类型。该表单会自动收集客户所选支付方式类型所需的所有支付详情。对于已通过身份验证的客户，`PaymentElement` 还会处理 Link 中已保存支付方式的显示。

Link 的身份验证、支付和收货地址 Elements 不需要位于同一页面。如果您在结账流程中分步骤向客户展示联系信息、收货信息和支付详情，则可以将每个 Element 放置在相应的步骤或页面中。在联系信息收集步骤中包含 Link 身份验证 Element 作为邮箱输入表单，以确保客户能够充分利用 Link 提供的自动填写功能。

如果您在结账流程早期通过 Link 身份验证 Element 收集了客户的邮箱地址，则无需在收货页面或支付页面再次显示该元素。

### 检索电子邮件地址

您可以使用 `linkAuthenticationElement` 组件上的 `onChange` 属性检索电子邮件地址详细信息。每当用户更新电子邮件字段或自动填充已保存的客户电子邮件时，`onChange` 处理程序就会触发。

```javascript
linkAuthenticationElement.on('change', (event) => {
  const email = event.value.email;
});
```

### 预填客户电子邮件地址

Link 身份验证 Element 接受邮箱地址。通过 `defaultValues` 选项提供客户的邮箱地址，可在客户进入支付页面后立即启动 Link 身份验证流程。

```javascript
// Create linkAuthentication element with the defaultValues option
const linkAuthenticationElement = elements.create("linkAuthentication", {defaultValues: {email: "foo@bar.com"}});

// Mount the Element to its corresponding DOM node
linkAuthenticationElement.mount("#link-authentication-element");
```

## Optional: 预填其他客户数据 [客户端]

如果有的话，预填客户信息可以进一步简化结账流程并减少手动数据输入。

#### 传入电子邮件

Payment Element 接受一个 `defaultValues.billingDetails` 对象，该对象允许您预先填写客户的姓名和电话号码以及他们的电子邮箱和收货地址。通过尽可能多地预填信息，您可以简化客户创建和重复使用 Link 账户的流程。
![Link 中的预填信息选择加入表单。](https://b.stripecdn.com/docs-statics-srv/assets/link-prefill-pe-new-user.aad0d37d3e3698f1aab307d020b95f90.png)

预先填写客户的电子邮箱地址、电话号码和姓名，以简化 Link 注册流程

您可以为 `defaultValues.billingDetails` 对象提供以下值：

| 值         | 必填 | 格式                                                  |
| --------- | -- | --------------------------------------------------- |
| `email`   | 必填 | 字符串                                                 |
| `name`    | 可选 | 字符串                                                 |
| `phone`   | 可选 | 字符串                                                 |
| `address` | 可选 | 带有 `postal_code` 和 `country` 字段的 JSON 对象。所有字段均为字符串。 |

将 `defaultValues.billingDetails` 传递到 Payment Element 取决于您是在 Payment Element 之前的单独页面上收集信息，还是在同一页面上收集信息。

#### 在 Payment Element 之前

如果您在 Payment Element 之前的单独页面上收集信息，则可以在创建 Payment Element 时通过传递 `defaultValues.billingDetails` 来预填值：

#### React

```jsx
  <PaymentElement
    options={{
      defaultValues: {
        billingDetails: {
          email: 'johnd@domain.com',
          name: 'John Doe',
          phone: '888-888-8888',
          address: {
            postal_code: '10001',
            country: 'US',
          }
        },
      },
    }}
  />;
```

#### HTML + JS

```javascript
const paymentElement = elements.create('payment', {
  defaultValues: {
    billingDetails: {
      email: 'johnd@domain.com',
      name: 'John Doe',
      phone: '888-888-8888',
      address: {
        postal_code: '10001',
        country: 'US',
      },
    },
  },
});

// Mount the Element to its corresponding DOM node
paymentElement.mount("#payment-element");
```

#### 与 Payment Element 相同的页面

如果您在与 Payment Element 相同的页面上收集信息，则可以通过使用 `defaultValues.billingDetails` 更新 Payment Element 来预填值。

```javascript
const paymentElement = elements.create('payment')
// Mount the Element to its corresponding DOM node
paymentElement.mount("#payment-element");

function updateValues() {
  paymentElement.update({
    defaultValues: {
      billingDetails: {
        email: document.getElementById('email').value, // Or whichever ID used for your fields
        name: document.getElementById('name').value,
        phone: document.getElementById('phone').value,
        address: {
          postal_code: document.getElementById('postal_code').value,
          country: document.getElementById('country').value,
        },
      },
    },
  });
}

const yourCollectionFieldIds = [
  'name',
  'email',
  'phone',
  'country',
  'postal_code',
];
// We recommend updating defaultValues only onBlur
yourCollectionFields.forEach((key) => {
  document.getElementById(key).onblur = function() {updateValues()};
});
```

#### 向 Link Authentication Element 传入电子邮件

如果您正在使用 Link 身份验证 Element，请将 `defaultValues.billingDetails` 对象添加到 Payment Element 中，以预填客户的姓名、电话号码以及收货地址。通过尽可能多地预填客户信息，您可以简化 Link 账户的创建和重复使用流程。
![Link 中的预填信息选择加入表单。](https://b.stripecdn.com/docs-statics-srv/assets/link-prefill-lae-new-user.56502b67c49281343f8f89b2bd7d889f.png)

预填客户的邮箱地址、电话号码和姓名，以简化 Link 的注册流程

您可以为 `defaultValues.billingDetails` 对象提供以下值：

| 值         | 必填 | 格式                                                  |
| --------- | -- | --------------------------------------------------- |
| `name`    | 可选 | 字符串                                                 |
| `phone`   | 可选 | 字符串                                                 |
| `address` | 可选 | 带有 `postal_code` 和 `country` 字段的 JSON 对象。所有字段均为字符串。 |

一个预填了所有值的 Payment Element 类似于以下示例：

#### React

```jsx
<PaymentElement
  options={{
    defaultValues: {
      billingDetails: {
        name: 'John Doe',
        phone: '888-888-8888',
        address: {
          postal_code: '10001',
          country: 'US',
        }
      },
    },
  }}
/>;
```

#### HTML + JS

```javascript
const paymentElement = elements.create('payment', {
  defaultValues: {
    billingDetails: {
      name: 'John Doe',
      phone: '888-888-8888',
      address: {
        postal_code: '10001',
        country: 'US',
      },
    },
  },
});

// Mount the Element to its corresponding DOM node
paymentElement.mount("#payment-element");
```

## Optional: 收集收货地址 [客户端]

#### 传入电子邮件

此集成选项不会收集客户的收货地址。如果您需要收集收货地址，请按照[“使用 Link Authentication Element”](https://docs.stripe.com/payments/link/add-link-elements-integration.md#collect-shipping)步骤中的说明，通过使用 Link Authentication Element、Address Element 和 Payment Element 来集成 Link。

#### 使用 Link Authentication Element

#### React

要收集地址，请创建一个空的 DOM 节点，供 [Address Element](https://docs.stripe.com/elements/address-element.md) 渲染其中。Address Element 必须显示在 Link 身份验证 Element 之后，以便 Link 能够自动填写客户保存的地址详情：

```jsx
import {loadStripe} from "@stripe/stripe-js";
import {
  Elements,
  LinkAuthenticationElement,AddressElement,
  PaymentElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

// Customize the appearance of Elements using the Appearance API.
const appearance = {/* ... */};

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

const CheckoutPage = ({clientSecret}) => (
  <Elements stripe={stripe} options={{clientSecret, appearance, loader}}>
    <CheckoutForm />
  </Elements>
);

export default function CheckoutForm() {
  return (
    <form>
      <h3>Contact info</h3>
      <LinkAuthenticationElement /><h3>Shipping</h3>
      <AddressElement options={{mode: 'shipping', allowedCountries: ['US']}} />
      <h3>Payment</h3>
      <PaymentElement />
      <button type="submit">Submit</button>
    </form>
  );
}
```

在 `PaymentElement` 前显示 `AddressElement`。`PaymentElement` 会动态检测由 `AddressElement` 收集的地址数据，隐藏不必要的字段，并在必要时收集额外的账单地址详情。

### 检索地址信息

当客户提交付款时，`AddressElement` 将自动传递收货地址，但您也可以用 `onChange` 属性在前端检索地址详情。每当用户更新 Address Element 中的任何字段，或选择保存的地址时，`onChange` 处理程序都会发送一个事件：

```jsx
<AddressElement onChange={(event) => {
  setAddressState(event.value);
}} />
```

### 预填充收货地址

使用 [defaultValues](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-defaultValues) 预填充地址信息，加速客户结账过程。

```jsx
<AddressElement options={{
  mode: 'shipping',
  defaultValues: {
    name: 'Jane Doe',
    address: {
      line1: '354 Oyster Point Blvd',
      line2: '',
      city: 'South San Francisco',
      state: 'CA',
      postal_code: '94080',
      country: 'US',
    }
  }
}}>
```

#### HTML + JS

[Address Element](https://docs.stripe.com/elements/address-element.md) 允许您收集收货地址或计费地址。为 Address Element 创建一个空的 DOM 节点。将其显示在 Link 身份验证 Element 之后：

```html
<form id="payment-form">
  <h3>Contact info</h3>
  <div id="link-authentication-element"></div><h3>Shipping</h3>
  <div id="address-element"></div>

  <h3>Payment</h3>
  <div id="payment-element"></div>

  <button type="submit">Submit</button>
</form>
```

然后，创建一个 Address Element 的实例，并将其挂载到 DOM 节点：

```javascript
// Customize the appearance of Elements using the Appearance API.
const appearance = { /* ... */ };

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

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

// Create an elements group from the Stripe instance passing in the clientSecret and, optionally, appearance.
const elements = stripe.elements({clientSecret, appearance, loader});

// Create Element instances
const linkAuthenticationElement = elements.create("linkAuthentication");const addressElement = elements.create("address", {
  mode: 'shipping',
  allowedCountries: ['US']
});
const paymentElement = elements.create("payment");

// Mount the Elements to their corresponding DOM node
linkAuthenticationElement.mount("#link-authentication-element");addressElement.mount("#address-element");
paymentElement.mount("#payment-element");
```

在 Payment Element 前显示 Address Element。Payment Element 会动态检测由 Address Element 收集的地址数据，隐藏不必要的字段，并在必要时收集额外的账单地址详情。

### 检索地址信息

当客户提交付款时，Address Element 将自动传递收货地址，但您也可以用 `change` 事件在前端检索地址详情。每当用户更新 Address Element 中的任何字段时，或在选择保存的地址之后，`change` 事件都会发送一个事件。

```javascript
addressElement.on('change', (event: AddressChangeEvent) => {
  const address = event.value;
})
```

### 预填充收货地址

使用 [defaultValues](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-defaultValues) 预填充地址信息，加速客户结账过程。

```javascript
// Create addressElement with the defaultValues option
const addressElement = elements.create("address", {
  mode: 'shipping',
  defaultValues: {
    name: 'Jane Doe',
    address: {
      line1: '354 Oyster Point Blvd',
      line2: '',
      city: 'South San Francisco',
      state: 'CA',
      postal_code: '94080',
      country: 'US',
    }
  }
});

// Mount the Element to its corresponding DOM node
addressElement.mount("#address-element");
```

## Optional: 自定义外观 [客户端]

将这些 Elements 添加到您的页面后，您可以自定义它们的 [appearance](https://docs.stripe.com/elements/appearance-api.md#theme)，使其适合您设计的其余部分：
![定制元素的外观](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.png)

定制元素的外观

## 向 Stripe 提交付款 [客户端]

用 [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) 完成付款，使用从不同 Elements 表单收集的客户信息完成付款。为该函数提供一个 [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url)，告诉 Stripe 在用户完成付款后将他们重定向到何处。

您的用户可能会先被重定向到一个中间站点，如银行授权页面，然后 Stripe 将其重定向到 `return_url`。

默认情况下，付款成功时，银行卡和银行付款将立即重定向到 `return_url`。如果不想重定向到 `return_url`，可以用 [if_required](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) 来更改行为。

#### React

```jsx
import {loadStripe} from "@stripe/stripe-js";
import {useStripe,
  useElements,
  Elements,
  LinkAuthenticationElement,
  PaymentElement,
  // If collecting shipping
  AddressElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = {/* ... */};

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

const CheckoutPage =({clientSecret}) => (
  <Elements stripe={stripe} options={{clientSecret, appearance, loader}}>
    <CheckoutForm />
  </Elements>
);

export default function CheckoutForm() {const stripe = useStripe();
  const elements = useElements();
const handleSubmit = async (event) => {
    event.preventDefault();

    const {error} = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: "https://example.com/order/123/complete",
      },
    });

    if (error) {
      // handle error
    }
  };

  return (<form onSubmit={handleSubmit}>
      <h3>Contact info</h3>
      <LinkAuthenticationElement />
      {/* If collecting shipping */}
      <h3>Shipping</h3>
      <AddressElement options={{mode: 'shipping', allowedCountries: ['US']}} />
      <h3>Payment</h3>
      <PaymentElement />

      <button type="submit">Submit</button>
    </form>
  );
}
```

#### HTML + JS

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

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // Show error to your customer (for example, payment details incomplete)
    console.log(error.message);
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});
```

`return_url` 对应于您的网站上的一个页面，在您呈现返回页面时提供 `PaymentIntent` 的[付款状态](https://docs.stripe.com/payments/payment-intents/verifying-status.md)。当 Stripe 将客户重定向到 `return_url` 时，您可以使用以下 URL 查询参数来验证付款状态。您还可以在提供 `return_url` 时附上自己的查询参数。这些查询参数会在重定向过程中持续存在。

| 参数                             | 描述                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent`               | `PaymentIntent` 的唯一标识符                                                                                                          |
| `payment_intent_client_secret` | `PaymentIntent` 对象的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)。 |

## Optional: 分离授权和捕获 [服务器端]

Link 支持[单独授权和捕获](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)。您必须在授权后 7 天内捕获已授权的 Link 付款。否则，授权将自动取消，且您无法捕获这笔付款。

### 告诉 Stripe 仅授权

要表明您想将单独授权和捕获，那么在创建 PaymentIntent 时将 [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) 设置为 `manual`。该参数可指示 Stripe 仅授权客户支付方式卡上的金额。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=link" \
  -d "payment_method_types[]=card" \
  -d amount=1099 \
  -d currency=usd \
  -d capture_method=manual
```

### 捕获资金

授权成功后，PaymentIntent 的 [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) 变为 `requires_capture`。要捕获授权资金，请发出 PaymentIntent [capture](https://docs.stripe.com/api/payment_intents/capture.md) 请求。默认会捕获授权的总金额——不能超出，但可以少于这个金额。

```curl
curl https://api.stripe.com/v1/payment_intents/{{PAYMENTINTENT_ID}}/capture \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount_to_capture=750
```

### (Optional) 取消授权

如果需要取消授权，您可以[取消 PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment)。

## 处理支付后事件 [服务器端]

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。[用 Webhook 接收这些事件](https://docs.stripe.com/webhooks/quickstart.md)并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

配置您的集成来侦听这些事件，而不是等待来自客户端的回调。当您等待来自客户端的回调时，客户可能在回调执行之前关闭浏览器窗口或退出应用。通过设置您的集成来侦听异步事件，您就能够使用单一集成接受[不同类型的支付方式](https://stripe.com/payments/payment-methods-guide)。

除了处理 `payment_intent.succeeded` 事件外，您还可以在使用 Payment Element 收款时处理另外两个重要事件：

| 活动                                                                                                                              | 描述                         | 操作                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | 在客户成功完成支付时从 Stripe 发送。     | 向客户发送订单确认通知，并*履行* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)他们的订单。 |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | 在客户尝试支付但支付未成功时从 Stripe 发送。 | 如果一笔付款从 `processing` 变为 `payment_failed`，则让客户再尝试一次。                                                                                                   |

## 测试集成

> 不要在*沙盒* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) Link 账户中存储真实用户数据。应将这些测试账户视为公开可用，因为它们与您的可发布密钥相关联。

目前，Link 仅支持信用卡、借记卡以及符合条件的美国银行账户购买。Link 需要进行[域名注册](https://docs.stripe.com/payments/payment-methods/pmd-registration.md)。

您可以使用任意有效的电子邮件地址为 Link 创建沙盒账户。下表展示了 Stripe 接受用于沙盒账户身份验证的固定一次性验证码值：

| 值             | 结果           |
| ------------- | ------------ |
| 非下方所列的任意 6 位数 | 成功           |
| 000001        | 错误，验证码无效     |
| 000002        | 错误，验证码已过期    |
| 000003        | 错误，超过了最大尝试次数 |

要测试具体的支付方式，请参考 [Payment Element 测试示例](https://docs.stripe.com/payments/accept-a-payment.md?platform=web#additional-testing-resources)。

### 多个资金来源

由于 Stripe 增加了额外的资金来源支持，因此您不需要更新您的集成。Stripe 会自动为它们提供与卡和银行账户支付相同的交易结算时间和担保。

### 卡验证和 3DS 验证

Link 支持银行卡支付的 *3DS 2.0 验证* (3D Secure 2 (3DS2) removes friction from the authentication process and improves the purchase experience compared to 3D Secure 1. It's the main card authentication method used to meet Strong Customer Authentication (SCA) requirements in Europe and is a key mechanism for businesses to request exemptions to SCA)身份验证。当支付时，3DS 2.0 要求客户与发卡行完成额外的验证步骤。使用 3DS 验证成功完成身份验证的支付将享受*责任转移* (With some 3D Secure transactions, the liability for fraudulent chargebacks (stolen or counterfeit cards) shifts from you to the card issuer)的保护。

要在沙盒环境中通过 Link 触发 3DS 2.0 身份验证挑战流程，请使用以下测试卡，并配合任意 CVC、邮政编码和未来的有效期：4000000000003220。

在沙盒环境中，身份验证过程显示一个模拟身份验证页面。在该页面，您可以授权或取消付款。授权付款 模拟的是身份验证成功的场景，并将您重定向到指定的返回 URL。点击**失败**按钮会模拟验证尝试不成功的场景。

有关更多详情，请参考 [3DS 验证页面](https://docs.stripe.com/payments/3d-secure.md)。

> 在测试 3DS 验证流程时，只有用于 3DS 2.0 的测试卡才能在 Link 上触发身份验证。

## Optional: 显示客户保存的数据 [服务器端] [客户端]

如果您的 Connect 平台使用[客户配置账户](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer)，请参阅我们的[指南](https://docs.stripe.com/connect/use-accounts-as-customers.md)，将代码中对 `Customer` 和事件的引用替换为相应的 Accounts v2 API 参考文件。

除了显示您为客户保存的地址和支付方式外，您还可以显示他们在 Link 中保存的数据。

如果客户有多个已保存的支付方式，除了客户通过 Link 保存的任何支付方式外，Stripe 还会显示保存在 *客户* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)对象中的最近使用过的三张银行卡。
![客户保存数据预览](https://b.stripecdn.com/docs-statics-srv/assets/customer-saved-data.bfbe4db974bbc852e87fe7dcd349a0ae.png)

要实现这一点，请创建一个临时密钥并将其与 *客户* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) ID 一起发送到您的前端。有关 `customer` 对象的信息是敏感信息，您不能在 Stripe.js 中直接检索它。Ephemeral Key 授予对 `customer` 数据的临时访问权限。

#### curl

```bash
curl https://api.stripe.com/v1/ephemeral_keys \
  -u<<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version:2026-03-25.dahlia" \
  -d "customer"="{{CUSTOMER_ID}}" \

curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -d "amount"=1099 \
  -d "currency"="usd" \-d "customer"="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"="link" \
  -d "payment_method_types[]"="card"
```

在客户端，用 `clientSecret` 获取 `customerOptions`。

```jsx
(async () => {
  const response = await fetch('/secret');const {clientSecret, customerOptions} = await response.json();
})
```

然后，将 `customerOptions.ephemeralKey` 和 `customerOptions.customer` 的值传递到 [Elements 组](https://docs.stripe.com/js/elements_object/create)上的 `customerOptions` 选项。加载 Stripe 实例时，还必须传递 `elements_customers_beta_1` Beta 标志。

#### React

```jsx
import {loadStripe} from "@stripe/stripe-js";
import {
  useStripe,
  useElements,
  Elements,
  LinkAuthenticationElement,
  PaymentElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('<<YOUR_PUBLISHABLE_KEY>>', {apiVersion: '2026-03-25.dahlia',
  betas: ['elements_customers_beta_1'],
});

const appearance = {/* ... */};

const loader = 'auto';

const CheckoutPage =({
  clientSecret,customerOptions,
}) => (

  <Elements stripe={stripe} options={{
    clientSecret,
    appearance,
    loader,customerOptions,
  }}>
    <CheckoutForm />
  </Elements>
);
```

#### HTML + JS

```javascript
// Customize the appearance of Elements using the Appearance API.
const appearance = { /* ... */ };

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>', {betas: ['elements_customers_beta_1'],
});

// Create an elements group from the Stripe instance, passing the clientSecret (obtained in step 2) and appearance (optional).
const elements = stripe.elements({
  clientSecret,
  appearance,
  loader,customerOptions,
});
```

## Optional: 保存 Link 支付方式 [服务器端] [客户端]

您可以保存 Link 支付方式，以用于未来的*非会话支付* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)或*订阅* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)，但不能用于未来的*会话内支付* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)。要实现这一点，您必须将支付方式关联到*客户* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)对象。当客户在您的业务中创建账户时，请创建一个 `customer` 对象。然后，在创建 PaymentIntent 时指定 `customer`。

当新客户与您的公司进行第一笔交易时，在 Stripe 中创建一个 `customer` 对象来存储其数据以备将来使用。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d "customer={{CUSTOMER_ID}}" \
  -d setup_future_usage=off_session
```

在最新版本的 API 中，指定 `automatic_payment_methods` 参数是可选的，因为 Stripe 默认启用其功能。

准备好再次对您的客户收款时，使用 `customer` 和生成的 *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) ID 创建一个新的 PaymentIntent。将 [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) 设置为 `true`。如果在客户未主动使用您的网站或应用时需要验证，这会导致 PaymentIntent 发送错误。

#### Accounts v2

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d payment_method={{PAYMENT_METHOD_ID}} \
  --data-urlencode "return_url=https://example.com/order/123/complete" \
  -d off_session=true \
  -d confirm=true
```

#### Customers v1

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d "customer={{CUSTOMER_ID}}" \
  -d payment_method={{PAYMENT_METHOD_ID}} \
  --data-urlencode "return_url=https://example.com/order/123/complete" \
  -d off_session=true \
  -d confirm=true
```

## 向您的客户披露 Stripe

Stripe 收集有关客户与 Elements 互动的信息，以向您提供服务、防范欺诈并改进其服务。这包括使用 Cookie 和 IP 地址来识别客户在单次结账会话中看到的 Elements。您有责任披露并获得 Stripe 以这些方式使用数据所需的所有权利和许可。有关更多信息，请访问我们的[隐私中心](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe)。

## See also

- [Link 是什么](https://docs.stripe.com/payments/link.md)
- [包含 Elements 的 Link](https://docs.stripe.com/payments/link/elements-link.md)
- [Payment Element 中的 Link](https://docs.stripe.com/payments/link/payment-element-link.md)
- [了解 Link Authentication Element](https://docs.stripe.com/payments/link/link-authentication-element.md)
- [不同支付集成中的 Link](https://docs.stripe.com/payments/link/link-payment-integrations.md)