# 收款

安全地在线上收款。

## 从这里开始：安装智能体技能

Stripe 建议使用官方技能，通过最佳实践与 API 进行集成。请按照以下说明了解具体方法。

\**提示：使用 curl 而非 Fetch 工具。**Skills 是 10–20 KB 的详细 Markdown 文件。Fetch 工具会对其进行摘要。使用 `curl -sL` 可确保获取完整内容。

**使用 `npx skills`**：检查系统是否已安装 `npx`。如果 `npx` 可用，运行 `npx skills add https://docs.stripe.com --list` 列出可用技能，然后运行 `npx skills add https://docs.stripe.com --yes --skill<skill-name> <--skill other-skills>` 以安装单个技能。

**如果 `npx skills` 不可用**：您可以使用 curl 从 `https://docs.stripe.com/.well-known/skills/index.json`. 获取可用技能的索引、功能描述及其文件。要下载技能及其相关文件，请使用 curl 从 `https://docs.stripe.com/.well-known/skills/<filepath>`. 下载。

本文建议使用以下技能：`stripe-best-practices`

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

 编码代理应安装 Stripe CLI（`npm i -g @stripe/cli`）并运行命令 `stripe sandbox create --help`，以配置一个含可用 API 密钥的匿名 Stripe 沙盒。无需注册账户。

制作支付表单或使用预构建的结账页面来开始接收线上付款。

# Payment Intents API


使用 [Stripe Elements](https://docs.stripe.com/payments/elements.md) 和 [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) 创建自定义支付表单。查看此集成[与 Stripe 其他集成类型的对比情况](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability)。

Payment Intents API 是一个底层 API，您可以用它来构建自己的结账或支付流程，但需要更多的代码和持续维护。对于大多数集成，我们推荐使用 [Payment Element 搭配 Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md)，因为它可实现与 PaymentIntent 相似的支付流程。进一步了解[何时应使用 Checkout Sessions 而非 PaymentIntent](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md)。

客户端侧面和服务器端代码构建接受各种支付方式的结账表单。

#### 集成难度
Complexity: 4/5
#### 集成类型

将 UI 组件组合到自定义支付流程

#### 用户界面自定义

使用 [Appearance API](https://docs.stripe.com/elements/appearance-api.md) 进行 CSS 级定制

> #### 想了解如何使用 Stripe Tax、折扣、配送或货币兑换？
> 
> Stripe 提供 Payment Element 集成功能，可自动为您处理税费、折扣、配送及货币转换事宜。如需了解更多信息，请参阅[构建结账页面](https://docs.stripe.com/payments/quickstart-checkout-sessions.md)。

## 设置 Stripe [服务器端]

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

 编码代理应安装 Stripe CLI（`npm i -g @stripe/cli`）并运行命令 `stripe sandbox create --help`，以配置一个含可用 API 密钥的匿名 Stripe 沙盒。无需注册账户。

用我们的官方库从您的应用程序访问 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 [服务器端]

> 如果您想在不先创建 PaymentIntent 的情况下呈现 Payment Element，请参阅[收集支付详情后再创建 Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment)。

[PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 对象用来表示您从客户收款的意图，跟踪扣款尝试及整个过程中的状态变化情况。
本文档从较高层次对支付集成进行了概述。 (See full diagram at https://docs.stripe.com/payments/accept-a-payment)
### 创建 PaymentIntent

在您的服务器上创建 PaymentIntent，设置好 [amount](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount) 和 [currency](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency)。在最新版的 API 中，可以选择性指定 `automatic_payment_methods` 参数，因为 Stripe 会默认开启其功能。您可以从[管理平台](https://dashboard.stripe.com/settings/payment_methods)管理支付方式。Stripe 根据交易金额、货币和支付流程等因素处理符合条件的支付方式的退货。

Stripe 会依据您的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)展示您已启用的支付方式。如果要查看客户所能看到的支付方式，请在[管理平台](https://dashboard.stripe.com/settings/payment_methods/review)中输入交易 ID，或设置订单金额与货币。如果要覆盖支付方式，请使用 [payment_method_types](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-payment_method_types) 属性，手动列出您希望启用的支付方式。

```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"
```

> 始终在服务器端决定扣款金额，这是一个可信的环境，客户端不行。这样可防止客户自己选择价格。

### 检索客户端私钥

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
```

## 收集付款详情 [客户端]

用 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 在客户端收集支付信息。Payment Element 是一个预构建的 UI 组件，它简化了多种支付方式的收集支付详情的流程。

Payment Element 中包含一个 iframe，它通过一个 HTTPS 连接安全地将支付信息发送到 Stripe。避免将 Payment Element 放在另一个 iframe 中，因为有些支付方式需要重定向到另一个页面进行付款确认。

如果您选择使用 iframe 并希望支持 Apple Pay 或 Google Pay，则必须将 iframe 的 [allow](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) 属性设置为`"payment *"`。

结账页面地址必须以 `https://` rather 开头，而非 `http://` for，您的集成才能正常工作。您可以在不使用 HTTPS 的情况下测试集成，但在准备接收真实付款时，请务必[启用 HTTPS](https://docs.stripe.com/security/guide.md#tls)。

#### HTML + JS

### 设置 Stripe.js

Payment Element 自动可以获取，这是 Stripe.js 的功能。在您的结账页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 `head` 部分。为保持 PCI 合规，始终从 js.stripe.com 加载 Stripe.js。不要把脚本打包或自行保留副本。

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

用下面的 JavaScript 在您的结账页面创建一个 Stripe 实例：

```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>>');
```

### 将 Payment Element 添加到您的支付页面

Payment Element 需要存在于您的支付页面的某个地方。用您的支付表单中的唯一 ID 创建一个空的 DOM 节点（容器）：

```html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>
```

加载了之前的表单后，创建一个 Payment Element 实例，并将它放入容器的 DOM 节点。创建 [Elements](https://docs.stripe.com/js/elements_object/create) 实例时，将上一步的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) 传入 `options`：

认真处理客户端私钥，因为它会完成收款。不要记录它，而是把它嵌入到 URL，或显示给除客户以外的所有人。

```javascript
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous stepconst elements = stripe.elements(options);

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

```

#### React

### 设置 Stripe.js

从 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 提供程序

要使用 Payment Element 组件，请将您的结账页面组件包裹在 [Elements 提供程序](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider)中。用您的公钥调用 `loadStripe`，并将返回的 `Promise` 传递到 `Elements` 提供程序。另外，将来自上一步的 [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) 作为 `options` 传递到 `Elements` 提供程序。

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

import CheckoutForm from './CheckoutForm';

// Make sure to call `loadStripe` outside of a component's render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

function App() {
  const options = {
    // passing the client secret obtained in step 3
    clientSecret: '{{CLIENT_SECRET}}',
    // Fully customizable with appearance API.
    appearance: {/*...*/},
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));
```

### 添加 Payment Element 组件

用 `PaymentElement` 组件构建您的表单。

```jsx
import React from 'react';
import {PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  return (
    <form><PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;
```

Stripe Element 是嵌入式 UI 组件的集合。要进一步定制您的表单，或收集其他客户信息，请浏览 [Element 文档](https://docs.stripe.com/payments/elements.md)。

Payment Element 呈现一个动态表单，您的客户可在这里选择一个支付方式。对于每个支付方式，表单会自动请求客户填写必要的支付详情。

### 自定义外观

您可以自定义 Payment Element，使其匹配您网站的设计风格，方法是在创建 `Elements` 提供程序时向 `options` 传递[外观对象](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance)。

### 收集地址

默认情况下，Payment Element 只收集必要的账单地址详情。某些行为，如[计算税费](https://docs.stripe.com/api/tax/calculations/create.md) 或输入配送详情，则需要客户的完整地址。您可以：

- 使用[Address Element](https://docs.stripe.com/elements/address-element.md)，利用自动填充和本地化功能收集客户的完整地址。这有助于确保税款计算达到最高准确性。
- 使用您自己的自定义表单收集地址详情。

### 申请 Apple Pay 商家令牌

如果您已将集成配置为[接受 Apple Pay 付款](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=checkout)，我们建议配置 Apple Pay 界面以返回商户令牌，从而支持商户发起的交易 (MIT)。在 Payment Element 中[请求相关商户令牌类型](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe)。

## Optional: 保存并检索客户支付方式

您可以配置 Payment Element 来保存客户的支付方式以备将来使用。本部分向您展示如何集成[保存的支付方式功能](https://docs.stripe.com/payments/save-customer-payment-methods.md)，从而让 Payment Element：

- 提示买家同意保存支付方式
- 买家同意时，存储支付方式
- 向买家显示已存储的支付方式，以方便日后购物使用
- 买家更换时[自动更新丢失或过期的银行卡](https://docs.stripe.com/payments/cards/overview.md#automatic-card-updates)
![Payment Element 和保存的支付方式复选框](https://b.stripecdn.com/docs-statics-srv/assets/spm-save.fe0b24afd0f0a06e0cf4eecb0ce2403a.png)

保存支付方式
![已选择保存了支付方式的 Payment Element](https://b.stripecdn.com/docs-statics-srv/assets/spm-saved.5dba5a8a190a9a0e9f1a99271bed3f4b.png)

复用以前保存的支付方式。

### 允许在 Payment Element 中保存支付方式

在服务端创建 [PaymentIntent](https://docs.stripe.com/api/payment_intents/.md) 时，需同步创建 [ CustomerSession ](https://docs.stripe.com/api/customer_sessions/.md)：提供客户 ID（`Customer` 对象使用 `customer`，客户配置型 `Account` 对象使用 `customer_account`），并为会话启用 [payment_element](https://docs.stripe.com/api/customer_sessions/object.md#customer_session_object-components-payment_element) 组件。配置需要启用的已保存支付方式[功能](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features)。例如，启用 [payment_method_save](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features-payment_method_save) 后，页面将展示勾选框，允许客户保存支付信息，用于后续付款。

您可在 PaymentIntent 或 Checkout Session 中指定 `setup_future_usage`，以此覆盖保存支付方式的默认行为。这一配置会自动保存支付方式供后续使用，即便客户未主动选择保存。若您已指定 `setup_future_usage`，请勿在同一笔支付交易中同时配置 `payment_method_save_usage`，否则会引发集成错误。

> #### 使用 Accounts v2 API 表示客户
> 
> Accounts v2 API 现已面向 Connect 用户全面开放，并向其他 Stripe 用户提供公开预览。如果您参与了 Accounts v2 预览，则需要在代码中指定[预览版本](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning)。
> 
> 要加入 Accounts v2 预览，请在您的管理平台中访问[账户预览与功能](https://dashboard.stripe.com/settings/previews)，并启用 **Global Payouts 的可重复使用支付方式**。
> 
> 在大多数应用场景下，我们建议[将您的客户建模为客户配置的 Account 对象](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md)，而不是使用 [Customer](https://docs.stripe.com/api/customers.md) 对象。

#### Accounts v2

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-intent-and-customer-session' do
  intent = client.v1.payment_intents.create({
    amount: 1099,
    currency: 'usd',
    automatic_payment_methods: {enabled: true},
    customer_account: {{CUSTOMER_ACCOUNT_ID}},
  })
  customer_session = client.v1.customer_sessions.create({
    customer_account: {{CUSTOMER_ACCOUNT_ID}},
    components: {
      payment_element: {
          enabled: true,
          features: {
            payment_method_redisplay: 'enabled',
            payment_method_save: 'enabled',
            payment_method_save_usage: 'off_session',
            payment_method_remove: 'enabled',
          },
        },
    },
  })
  {
    client_secret: intent.client_secret,
    customer_session_client_secret: customer_session.client_secret
  }.to_json
end
```

#### Customers v1

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

post '/create-intent-and-customer-session' do
  intent = client.v1.payment_intents.create({
    amount: 1099,
    currency: 'usd',
    # In the latest version of the API, specifying the `automatic_payment_methods` parameter
    # is optional because Stripe enables its functionality by default.
    automatic_payment_methods: {enabled: true},
    customer: {{CUSTOMER_ID}},
  })
  customer_session = client.v1.customer_sessions.create({
    customer: {{CUSTOMER_ID}},
    components: {
      payment_element: {
          enabled: true,
          features: {
            payment_method_redisplay: 'enabled',
            payment_method_save: 'enabled',
            payment_method_save_usage: 'off_session',
            payment_method_remove: 'enabled',
          },
        },
    },
  })
  {
    client_secret: intent.client_secret,
    customer_session_client_secret: customer_session.client_secret
  }.to_json
end
```

您的 Element 实例使用 CustomerSession 的*客户端私钥* (A client secret is used with your publishable key to authenticate a request for a single object. Each client secret is unique to the object it's associated with)来访问该客户保存的支付方式。创建 CustomerSession 时正确[处理错误](https://docs.stripe.com/error-handling.md)。如果发生错误，您不需要向 Element 实例提供 CustomerSession 客户端私钥，因为它是可选的。

使用PaymentIntent 和 CustomerSession 的客户端私钥创建 Element 实例。然后，用这个 Element 实例创建一个 Payment Element。

```javascript
// Create the CustomerSession and obtain its clientSecret
const res = await fetch("/create-intent-and-customer-session", {
  method: "POST"
});

const {
  customer_session_client_secret: customerSessionClientSecret
} = await res.json();

const elementsOptions = {
  clientSecret: '{{CLIENT_SECRET}}',customerSessionClientSecret,
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret
// and CustomerSession's client secret obtained in a previous step
const elements = stripe.elements(elementsOptions);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');
```

确认 PaymentIntent 时，Stripe.js 会自动控制 PaymentIntent 上的 [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) 设置和 PaymentMethod 上的 [allow_redisplay](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-allow_redisplay)，具体取决于客户是否勾选保存其付款详情的框。

### 强制重新收集卡安全码 (CVC)

可以选择在 [when creating the PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-card-require_cvc_recollection) 指定 `require_cvc_recollection`，以在客户用银行卡支付时强制重新收集 CVC。

### 检测选择的已保存支付方式

要在选择了保存的支付方式时控制动态内容，请侦听 Payment Element `change` 事件（该事件会填充上所选的支付方式）。

```javascript
paymentElement.on('change', function(event) {
  if (event.value.payment_method) {
    // Control dynamic content if a saved payment method is selected
  }
})
```

## Optional: Link in your checkout page [客户端]

通过在 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 中使用 [Link](https://docs.stripe.com/payments/link.md)，让您的客户结账更快捷。您可以为任何已登录并使用 Link 的客户自动填写信息，无论他们最初是在其他商家的 Link 中保存的信息。默认的 Payment Element 集成在卡片表单中包含了 Link 提示。要管理 Payment Element 中的 Link，请前往您的 [支付方式设置](https://dashboard.stripe.com/settings/payment_methods)。
![结账时直接在 Payment Element 中验证或注册 Link](https://b.stripecdn.com/docs-statics-srv/assets/link-in-pe.2efb5138a4708b781b8a913ebddd9aba.png)

收集客户电子邮件地址以进行 Link 验证或注册

### 集成选项

您可以通过两种方式将 Link 与 Payment Element 集成。其中，Stripe 建议在可用的情况下将客户邮箱地址传递给 Payment Element。在决定使用哪种方案时，请务必考虑您的结账流程：

| 集成选项                                       | 结账流程                                                                     | 描述                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| 向 Payment Element 传递客户电子邮件地址 (Recommended) | - 您的客户在登入结账页面前先输入他们的电子邮件地址（例如，在之前的账户创建步骤）。
  - 您偏向于使用自己的电子邮件输入栏。         | 通过编程方式将客户邮箱地址传递给 Payment Element。在此情境下，客户直接在支付表单中（而非通过单独的用户界面组件）进行 Link 身份验证。                   |
| 在 Payment Element 中收集客户电子邮件地址              | - 您的客户可以在结账时选择直接在 Payment Element 中输入邮箱地址，并进行 Link 的身份验证或注册。
  - 无须修改代码。 | 如果客户尚未注册 Link，并在 Payment Element 中选择了一种支持的支付方式，系统会提示他们使用 Link 保存其支付详情。对于已注册的客户，Link 会自动填写其支付信息。 |

使用[defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) 将客户电子邮件地址传递给 Payment Element。

```javascript
const paymentElement = elements.create('payment', {
  defaultValues: {
    billingDetails: {
      email: 'foo@bar.com',
    }
  },
  // Other options
});
```

如需了解更多信息，请阅读如何[构建包含 Link 的自定义结账页面](https://docs.stripe.com/payments/link/add-link-elements-integration.md)。

## Optional: 从服务器获取更新 [客户端]

呈现了 Payment Element 之后，您可能想更新 PaymentIntent 的属性，例如 [amount](https://docs.stripe.com/api/payment_intents/update.md#update_payment_intent-amount)（例如，折扣码或运费）。您可以在您的服务器上 [update the PaymentIntent](https://docs.stripe.com/api/payment_intents/update.md)，然后调用 [elements.fetchUpdates](https://docs.stripe.com/js/elements_object/fetch_updates) 来查看 Payment Element 中反映的金额。该例显示了如何创建更新 PaymentIntent 上的金额的服务器端点：

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
get '/update' do
  intent = client.v1.payment_intents.update(
    '{{PAYMENT_INTENT_ID}}',
    {amount: 1499},
  )
  {status: intent.status}.to_json
end
```

该例演示了如何更新 UI 来在客户端体现这些变化。

```javascript
(async () => {
  const response = await fetch('/update');
  if (response.status === 'requires_payment_method') {
    const {error} = await elements.fetchUpdates();
  }
})();
```

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

使用 [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment)，用来自 Payment Element 的详情完成付款。为该函数提供一个 [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url)，告诉 Stripe 在用户完成付款后将他们重定向到哪里。您的用户可能会先被重定向到一个中间站点，如银行授权页面，然后才被重定向到 `return_url`。付款成功时，银行卡付款将立即重定向到 `return_url`。

如果您不想在完成付款后对银行卡付款重定向，可以将[重定向](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect)设置到 `if_required`。这样就会只重定向使用基于重定向的支付方式结账的客户。

#### HTML + JS

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

form.addEventListener('submit', async (event) => {
  event.preventDefault();
const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = 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`.
  }
});
```

#### React

从您的支付表单组件调用 [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) 时，使用 [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) 和 [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook) 钩子。

如果您不想用 hooks，而是想使用传统的类组件 (Class Components)，则可以使用 [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer)。

```jsx
import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();

  const [errorMessage, setErrorMessage] = useState(null);

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    if (!stripe || !elements) {
      // Stripe.js hasn't yet loaded.
      // Make sure to disable form submission until Stripe.js has loaded.
      return;
    }
const {error} = await stripe.confirmPayment({
      //`Elements` instance that was used to create the Payment Element
      elements,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
    });


    if (error) {
      // This point will only be reached if there is an immediate error when
      // confirming the payment. Show error to your customer (for example, payment
      // details incomplete)
      setErrorMessage(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 (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button disabled={!stripe}>Submit</button>
      {/* Show error message to your customers */}
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  );
};

export default CheckoutForm;
```

确保 `return_url` 对应于您网站上显示付款状态的一个页面。Stripe 将客户重定向到 `return_url` 时，我们会提供以下 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)。 |

> 如果您有可以用来跟踪客户浏览器会话的工具，则您可能需要将 `stripe.com` 域名添加到推荐人列表。重定向会导致一些工具创建新的会话，从而阻止您跟踪完整的会话。

用以下某个查询参数检索 PaymentIntent。检查 [PaymentIntent 的状态](https://docs.stripe.com/payments/paymentintents/lifecycle.md)，以决定向客户显示的内容。您还可以在提供 `return_url` 时附加自己的查询参数，它们会在重定向过程中持续存在。

#### HTML + JS

```javascript

// Initialize Stripe.js using your publishable key
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});
```

#### React

```jsx
import React, {useState, useEffect} from 'react';
import {useStripe} from '@stripe/react-stripe-js';

const PaymentStatus = () => {
  const stripe = useStripe();
  const [message, setMessage] = useState(null);

  useEffect(() => {
    if (!stripe) {
      return;
    }

    // Retrieve the "payment_intent_client_secret" query parameter appended to
    // your return_url by Stripe.js
    const clientSecret = new URLSearchParams(window.location.search).get(
      'payment_intent_client_secret'
    );

    // Retrieve the PaymentIntent
    stripe
      .retrievePaymentIntent(clientSecret)
      .then(({paymentIntent}) => {
        // Inspect the PaymentIntent `status` to indicate the status of the payment
        // to your customer.
        //
        // Some payment methods will [immediately succeed or fail][0] upon
        // confirmation, while others will first enter a `processing` state.
        //
        // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
        switch (paymentIntent.status) {
          case 'succeeded':
            setMessage('Success! Payment received.');
            break;

          case 'processing':
            setMessage("Payment processing. We'll update you when payment is received.");
            break;

          case 'requires_payment_method':
            // Redirect your user back to your payment page to attempt collecting
            // payment again
            setMessage('Payment failed. Please try another payment method.');
            break;

          default:
            setMessage('Something went wrong.');
            break;
        }
      });
  }, [stripe]);


  return message;
};

export default PaymentStatus;
```

### 收集钱包信息

如果您接受 Apple Pay 或 Google Pay，请在提交处理程序开头调用 [elements.submit()](https://docs.stripe.com/js/elements/submit)。这会触发表单验证并显示原生支付页面，以便您的客户可以授权支付。

#### HTML + JS

```javascript
form.addEventListener('submit', async (event) => {
  event.preventDefault();
// Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Confirm the payment
});
```

#### React

```jsx
const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe || !elements) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }
// Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Confirm the payment
};
```

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

付款完成时，Stripe 会发送一个 [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) 事件。使用 [管理平台 Webhook 工具](https://dashboard.stripe.com/webhooks)、或按照 [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)           | 客户成功完成付款时发送。                                                                                                  | 向客户发送订单确认通知，并*履行* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)他们的订单。 |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | 当客户成功发起付款但并未完成时发送。当客户发起银行借记时，通常会发送此事件。之后将会出现 `payment_intent.succeeded` 或 `payment_intent.payment_failed` 事件。 | 向客户发送订单确认，告知他们的付款正等待处理。对于数字商品，您可能想先履行订单，然后再等付款完成。                                                                                                     |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | 在客户尝试付款但付款失败时发送。                                                                                              | 如果一笔付款从 `processing` 变为 `payment_failed`，则让客户再尝试一次。                                                                                                   |

## 测试您的集成

要测试您的自定义支付集成：

1. 创建 Payment Intent 并检索客户端私钥。
2. 使用下表中的方法填写付款详情。
   - 输入一个任意的未来日期作为有效期。
   - 输入 3 位数 CVC（银行卡安全码）。
   - 输入账单地址邮编。
3. 向 Stripe 提交付款。您将被重定向到您的 `return_url`。
4. 前往管理平台，在[付款页面](https://dashboard.stripe.com/test/payments?status%5B0%5D=successful)上查找付款。如果您付款成功，就会在列表中看到它。
5. 点击您的付款，查看更多详情，例如账单信息及已购商品列表。您可以此信息来履行订单。

了解有关[测试您的集成](https://docs.stripe.com/testing.md)的更多信息。

#### 银行卡

| 卡号                  | 场景                                                                                                                                                                                                                                                             | 如何测试                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| 4242424242424242    | 该卡付款成功，不需要验证。                                                                                                                                                                                                                                                  | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |
| 4000002500003155    | 该卡付款时需要*验证* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase)。 | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |
| 4000000000009995    | 该卡被拒绝，显示拒付代码，例如 `insufficient_funds`。                                                                                                                                                                                                                          | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |
| 6205500000000000004 | 银联卡的长度为 13-19 位。                                                                                                                                                                                                                                               | 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 |

#### 钱包

| 支付方式   | 场景                                                                                                      | 如何测试                                                |
| ------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Alipay | 您的客户通过基于重定向和[立即通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)的支付方式成功付款。 | 选择基于重定向的任意支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**测试付款成功**。 |

#### 银行重定向

| 支付方式                              | 场景                                                                                                      | 如何测试                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| BECS 直接借记                         | 您的客户成功用 BECS 直接借记完成付款。                                                                                  | 使用帐号 `900123456` 和 BSB `000000` 填写表格。确认的 PaymentIntent 先转入 `processing`，3 分钟后转为 `succeeded` 状态。   |
| BECS 直接借记                         | 您的客户付款失败，错误代码为：`account_closed`。                                                                        | 使用帐号 `111111113` 和 BSB `000000` 填写表格。                                                             |
| Bancontact、EPS、iDEAL 和 Przelewy24 | 您的客户在基于重定向和立即通知型的支付方式的重定向页面验证失败。                                                                        | 选择基于重定向的任意支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**让测试付款失败**。                                              |
| 通过银行支付                            | 您的客户通过基于重定向和[延迟通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)的支付方式成功付款。 | 选择支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**测试付款成功**。                                                       |
| 通过银行支付                            | 您的客户在基于重定向和延迟通知型的支付方式的重定向页面验证失败。                                                                        | 选择支付方式，填写必要的信息，并确认付款。然后在重定向页面上点击**让测试付款失败**。                                                      |
| BLIK                              | 有多个 BLIK 支付失败的情况——立即失败（例如，代码已过期或无效）、延迟的错误（银行拒付）或超时（客户未及时响应）。                                            | 使用电子邮件模式[模拟不同的失败情况](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)。 |

#### 银行借记

| 支付方式      | 场景                                                      | 如何测试                                                                  |
| --------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
| SEPA 直接借记 | 您的客户成功用 SEPA 直接借记完成付款。                                  | 用账号 `AT321904300235473204` 填写表单。确认的 PaymentIntent 最初变为处理中，三分钟后变为成功状态。 |
| SEPA 直接借记 | 您的客户的付款意图状态从 `processing` 变为 `requires_payment_method`。 | 用账号 `AT861904300235473202` 填写表单。                                      |

#### 付款凭单

| 支付方式         | 场景                          | 如何测试                                 |
| ------------ | --------------------------- | ------------------------------------ |
| Boleto, OXXO | 您的客户用 Boleto 或 OXXO 付款凭单付款。 | 选择 Boleto 或 OXXO 此支付方式并提交付款。出现后关闭对话。 |

有关测试您的集成的更多信息，请参阅[测试](https://docs.stripe.com/testing.md)部分。

## Optional: 添加更多支付方式

Payment Element 默认[支持很多种支付方式](https://docs.stripe.com/payments/payment-methods/integration-options.md#choose-how-to-add-payment-methods)。需进行额外步骤才能启用并显示某些支付方式。

### Affirm

开始使用 Affirm 时，必须在[管理平台](https://dashboard.stripe.com/settings/payment_methods)中启用它。用 Affirm 支付方式创建 PaymentIntent 时，您需要包含[收货地址](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-shipping)。该例建议在客户[选择了他们的支付方式](https://docs.stripe.com/payments/accept-a-payment.md#web-create-intent)后在客户端传递配送信息。进一步了解如何通过 Stripe 使用 [Affirm](https://docs.stripe.com/payments/affirm.md)。

#### HTML + JS

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

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

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://my-site.com/order/123/complete',shipping: {
        name: 'Jenny Rosen',
        address: {
          line1: '1 Street',
          city: 'Seattle',
          state: 'WA',
          postal_code: '95123',
          country: 'US'
        }
      },

    }
  });

  if (error) {
    // This point is reached if there's an immediate error when
    // confirming the payment. Show error to your customer (for example,
    // payment details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});
```

#### React

```jsx

import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();

  const [errorMessage, setErrorMessage] = useState(null);

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    if (!stripe || !elements) {
      // Stripe.js hasn't yet loaded.
      // Make sure to disable form submission until Stripe.js has loaded.
      return;
    }

    const {error} = await stripe.confirmPayment({
      //`Elements` instance that was used to create the Payment Element
      elements,
      confirmParams: {
        return_url: 'https://my-site.com/order/123/complete',shipping: {
          name: 'Jenny Rosen',
          address: {
            line1: '1 Street',
            city: 'Seattle',
            state: 'WA',
            postal_code: '95123',
            country: 'US'
          }
        },

      }
    });


    if (error) {
      // This point will only be reached if there is an immediate error when
      // confirming the payment. Show error to your customer (for example,
      // payment details incomplete)
      setErrorMessage(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 (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button disabled={!stripe}>Submit</button>
      {/* Show error message to your customers */}
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  )
};

export default CheckoutForm;
```

#### 测试 Affirm

了解如何通过下表测试不同场景：

| 场景                       | 如何测试                        |
| ------------------------ | --------------------------- |
| 您的客户通过 Affirm 成功付款。      | 填写表单（务必包含收货地址）并授权付款。        |
| 您的客户未在 Affirm 重定向页面进行验证。 | 填写表单，然后在重定向页面上点击**测试付款失败**。 |

### Afterpay (Clearpay)

用 Afterpay 支付方式创建 PaymentIntent 时，您需要包含[收货地址](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-shipping)。进一步了解如何通过 Stripe 使用 [Afterpay](https://docs.stripe.com/payments/afterpay-clearpay.md)。

您可以在[管理平台](https://dashboard.stripe.com/settings/payment_methods)中管理支付方式。Stripe 会根据交易金额、币种以及支付流程等因素，自动返回符合条件的支付方式。在最新版本的 API 中，指定 `automatic_payment_methods` 参数为可选项，因为 Stripe 默认已启用该功能。请确保您已在[管理平台](https://dashboard.stripe.com/settings/payment_methods)中启用 Afterpay / Clearpay。

```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 "shipping[name]=Jenny Rosen" \
  -d "shipping[address][line1]=1234 Main Street" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][state]=CA" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][postal_code]=94111"
```

#### 测试 Afterpay (Clearpay)

了解如何通过下表测试不同场景：

| 场景                         | 如何测试                        |
| -------------------------- | --------------------------- |
| 您的客户通过 Afterpay 成功付款。      | 填写表单（务必包含收货地址）并授权付款。        |
| 您的客户未在 Afterpay 重定向页面进行验证。 | 填写表单，然后在重定向页面上点击**测试付款失败**。 |

### Apple Pay 和 Google Pay

当您[启用银行卡支付](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#create-the-paymentintent)时，我们会为符合[钱包显示条件](https://docs.stripe.com/testing/wallets.md)的客户显示 Apple Pay 和 Google Pay。要接受来自这些钱包的付款，您还必须：

- 在您的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)中启用它们。Apple Pay 默认启用。
- 在 HTTPS 的开发和生产环境中为您的应用服务。
- [注册您的域名](https://docs.stripe.com/payments/payment-methods/pmd-registration.md)。
- 如果您更新了 [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 的金额，请[从服务器获取更新](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#fetch-updates)，以保持钱包支付模态同步。

> #### 区域测试
> 
> Stripe Elements 不支持印度 Stripe 账户和客户的 Google Pay 或 Apple Pay。因此，如果测试者的 IP 地址在印度，您就不能测试您的 Google Pay 或 Apple Pay 集成，即使 Stripe 账户是在印度境外开立的也一样。

进一步了解如何通过 Stripe 使用 [Apple Pay](https://docs.stripe.com/apple-pay.md) 和 [Google Pay](/google-pay](/google-pay)。

### ACH 直接借记

通过ACH 直接借记支付方式使用 Payment Element 时，按照以下步骤操作：

1. 创建客户配置的 [Account](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) 对象或 [Customer](https://docs.stripe.com/api/customers/create.md) 对象来代表您的客户。

#### Accounts v2

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-06-24.preview" \
  --json '{
    "configuration": {
        "customer": {}
    }
  }'
```

#### Customers v1

```curl
curl -X POST https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:"
```

1. 创建 `PaymentIntent` 时指明客户 ID。

   #### 账户 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 setup_future_usage=off_session \
     -d "customer_account={{CUSTOMERACCOUNT_ID}}"
   ```

   #### 客户 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 setup_future_usage=off_session \
     -d "customer={{CUSTOMER_ID}}"
   ```

2. 选择一个[验证方式](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-payment_method_options-us_bank_account-verification_method)。

通过 Payment Element 使用 ACH 直接借记支付方式时，您只能选择 `automatic` 或 `instant`。

进一步了解如何通过 Stripe 使用 [ACH 直接借记](https://docs.stripe.com/payments/ach-direct-debit.md)。

#### 测试 ACH 直接借记

| 场景                         | 如何测试                                                                                                                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 您的客户通过即时验证方式成功用美国银行账户完成付款。 | 选择**美国银行账户**并填写表单。点击测试机构。按照模态上的说明关联您的银行账户。点击您的付款按钮。                                                                                                                                     |
| 您的客户通过微存款方式成功用美国银行账户完成付款。  | 选择**美国银行账户**并填写表格。点击**手动输入银行账户详情**。按照模态框中的说明关联您的银行账户。您可以使用这些[测试账户号码](https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment.md?platform=web#test-account-numbers)。点击您的支付按钮。 |
| 您的客户在完成银行账户关联过程时会失败。       | 选择 **美国银行账户** 并点击测试机构或 **改为手动输入银行详情** 。关闭模态，不要完成它。                                                                                                                                      |

### BLIK

结合使用 Payment Element 与 BLIK 时，用户可以关闭提示他们在其银行应用程序中授权付款的模态。这将触发向您的 `return_url` 重定向的操作，不会将客户返回到结账页面。进一步了解如何通过 Stripe 使用 [BLIK](https://docs.stripe.com/payments/blik.md)。

处理用户关闭模态的情况时，在您的 `return_url` 的服务器端处理程序上，观察 Payment Intent 的 `status`，看它是 `succeeded` 还是仍然为 `requires_action`（说明用户在未授权的情况下关闭了模态），然后根据实际情况酌情处理。

### 二维码支付方式

通过特定支付方式（微信支付、PayNow、Pix、PromptPay、Cash App Pay）的二维码使用 Payment Element 时，用户可关闭二维码模态。这将触发向您的 `return_url` 重定向的操作，不会将客户返回到结账页面。

处理用户关闭二维码模态的情况时，在您的 `return_url` 的服务器端处理程序上，观察 Payment Intent 的 `status`，看它是 `succeeded` 还是仍然为 `requires_action`（说明用户在未支付的情况下关闭了模态），然后根据实际情况酌情处理。

或者，可通过传递高级可选参数 [`redirect=if_required`](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect)，它可以防止在管理二维码模态时进行重定向，进而可防止自动重定向到您的 `return_url`。

### Cash App Pay

Payment Element 在桌面网页或移动端网页中以不同的方式呈现动态表单，因为它使用的是不同的客户身份验证方式。进一步了解如何通过 Stripe 使用 [Cash App Pay](https://docs.stripe.com/payments/cash-app-pay.md)。

#### 移动端网页应用程序元素

Cash App Pay 是一种基于重定向的移动端网页支付方式。它会将您的客户重定向到真实模式下的 Cash App 或测试模式下的测试页面。完成付款后，无论您是否设置了 `redirect=if_required`，它们都会被重定向到 `return_url`。

#### 桌面网页应用程序元素

Cash App Pay 是桌面网页中的一种二维码支付方式，其中 Payment Element 呈现一种二维码模态。您的客户需要用二维码扫描应用程序或 Cash App 移动应用程序来扫描二维码。

在真实模式下，一旦客户被重定向到 Cash App，它就会立即将客户重定向到 `return_url`。在测试环境下，他们可以在被重定向到 `return_url` 之前批准或拒绝付款。客户也可以在完成支付前关闭二维码模态，这将触发向您的 `return_url` 重定向的操作。

确保 `return_url` 对应于您的网站上检查 Payment Intent 的 `status` 的一个页面。Payment Intent `status` 可以是 `succeeded`、`failed` 或 `requires_action`（例如，客户已在未扫描二维码的情况下关闭模态）。

或者，可通过传递高级可选参数 `redirect=if_required`，它可以防止在管理二维码模态时进行重定向，进而可防止自动重定向到您的 `return_url`。

### PayPal

要使用 PayPal，请务必使用[注册域名](https://docs.stripe.com/payments/payment-methods/pmd-registration.md)。

## 向您的客户披露 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

- [Stripe Element](https://docs.stripe.com/payments/elements.md)
- [设置未来付款](https://docs.stripe.com/payments/save-and-reuse.md)
- [支付过程中保存付款详情](https://docs.stripe.com/payments/save-during-payment.md)
- [在您的支付流程中计算销售税、商品及服务税和增值税](https://docs.stripe.com/tax/standalone-tax-api.md)