# 接受银行转账

用 Payment Intents API 接受银行转账付款。

当您第一次接受客户的银行转账付款时，Stripe 会为他们生成一个虚拟银行账户，然后您可以直接分享给他们。今后来自该客户的所有银行转账付款都会发到此银行账户。在一些国家，Stripe 还为您提供一个独特的转账参考码，您的客户每次转账时都需包含此号码，以更方便地进行对账。在某些国家，可以免费创建的虚拟银行账号数量是有限制的。

下图概括介绍了接受银行转账付款时的常用步骤：

#### 用账单
接受银行转账付款时的一般步骤 (See full diagram at https://docs.stripe.com/payments/bank-transfers/accept-a-payment)
#### 不用账单
![](https://b.stripecdn.com/docs-statics-srv/assets/without-invoices-diagram-1.a17fe04695ef532427f25a9e1276ee2e.svg)

## 处理少付和多付

通过银行转账付款时，客户的实际转账金额有可能多于或少于预期付款金额。如果客户转账金额不足，Stripe 会先将收到的部分款项记入未结的 Payment Intent 中。但账单不会部分入账，将在全额到账前保持未结状态。

如果客户支付的金额超过预期金额，Stripe 会尝试核对收到的金额和未结金额，并将剩余的超出金额保留在客户余额中。了解更多有关 [Stripe 如何处理对账](https://docs.stripe.com/payments/customer-balance/reconciliation.md) 的信息。

#### 用账单

客户少付时：
客户发送了一笔小于预期金额的银行转账 (See full diagram at https://docs.stripe.com/payments/bank-transfers/accept-a-payment)
客户多付时：
客户发送了一笔大于预期金额的银行转账 (See full diagram at https://docs.stripe.com/payments/bank-transfers/accept-a-payment)
#### 不用账单
![](https://b.stripecdn.com/docs-statics-srv/assets/without-invoices-diagram-2.464fe916d5822422144c8aea0f31ed45.svg)
![](https://b.stripecdn.com/docs-statics-srv/assets/without-invoices-diagram-3.b1992851a5f3492d14eaa35e336b0e9f.svg)

## 多个开启付款或账单的处理

您可能有多个开启的付款或账单，可通过银行转账来支付。在默认设置中，Stripe 会尝试用诸如转账的参考码或转账金额来[自动对账](https://docs.stripe.com/payments/customer-balance/reconciliation.md)银行转账。

您可以禁用自动对账，然后自行[手动对账](https://docs.stripe.com/payments/customer-balance/reconciliation.md#cash-manual-reconciliation)付款和账单。可单独覆盖掉对某个客户的自动对账行为，方法是将[对账模式](https://docs.stripe.com/api/customers/create.md#create_customer-cash_balance-settings-reconciliation_mode)设置为手动模式。

# Checkout

> This is a Checkout for when payment-ui is checkout. View the full page at https://docs.stripe.com/payments/bank-transfers/accept-a-payment?payment-ui=checkout.

> Stripe 可以通过评估货币、付款方式限制和其他参数，自动为客户展示相关支付方式。
> 
> - 请遵循[接受付款](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=stripe-hosted)指南，构建一个使用[动态支付方式](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)的 Checkout 集成。
- 如果您不想使用动态支付方式，请按照以下步骤在 Checkout 集成中手动配置支付方式。

银行转账是 Checkout 的一种[一次性使用](https://docs.stripe.com/payments/payment-methods.md#usage)支付方式，客户利用显示的付款说明，通过银行转账方式支付。选择支付时，用户将跳转到一个托管页面，其中显示有银行转账说明和转账付款的状态。

银行转账也是一种*延迟通知型支付方式* (A payment method that can't immediately return payment status when a customer attempts a transaction (for example, ACH debits). Businesses commonly hold an order in a pending state until payment is successful with these payment methods)，这意味着支付后资金不会立即可用。

> 对于在会话创建请求中未包含现有 [Customer object](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) 的 Checkout Session，不能使用银行转账方式。

## 确定兼容性

**支持的商家所在地**：Europe (SEPA area), UK, JP, MX, US

**支持的货币**：`eur, gbp, jpy, mxn, usd`

**展示货币**：`eur, gbp, jpy, mxn, usd`

**支付模式**：Yes

**设置模式**：No

**订阅模式**：No

Checkout Session 必须满足以下所有条件才能支持 Bank Transfer 付款：

- 所有行项目的*价格* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions)都必须使用同一币种。如果您的某些行项目使用的是不同币种，则为每个币种单独创建 Checkout Sessions。

- 您只能使用一次性行项目（银行转账 Checkout Session 不支持经常性*订阅* (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)方案）。

## 收款

> 使用本指南之前，先构建一个集成来用 Checkout [接受付款](https://docs.stripe.com/payments/accept-a-payment.md?integration=checkout)。

使用本指南启用 Bank Transfer。

### 创建或检索 Customer

要核对每笔银行转账付款，您必须关联一个 [Customer](https://docs.stripe.com/api/customers.md) 对象。如果您有现成的 Customer 对象，则可以跳过这一步。否则，创建一个新的 Customer 对象。

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

### 启用 Bank Transfer 这一支付方式

创建新的 [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) 时，您需要：

1. 设置 `customer`
1. 将 `customer_balance` 添加到 `payment_method_types` 列表
1. 确保您的所有 `line_items` 都使用相同的货币

#### US

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][currency]"=usd \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d "payment_method_types[0]"=card \
  -d "payment_method_types[1]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=us_bank_transfer \
  --data-urlencode success_url="https://example.com/success"
```

#### UK

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][currency]"=gbp \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d "payment_method_types[0]"=card \
  -d "payment_method_types[1]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=gb_bank_transfer \
  --data-urlencode success_url="https://example.com/success"
```

#### EU

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d "payment_method_types[0]"=card \
  -d "payment_method_types[1]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=eu_bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]"=FR \
  --data-urlencode success_url="https://example.com/success"
```

将 [payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-eu_bank_account-country) 设置为 `BE`、`DE`、`FR`、`IE` 或 `NL` 之一，以便向客户显示本地化的 IBAN。

#### JP

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][currency]"=jpy \
  -d "line_items[0][price_data][product_data][name]"="Tシャツ" \
  -d "line_items[0][price_data][unit_amount]"=19000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d "payment_method_types[0]"=card \
  -d "payment_method_types[1]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=jp_bank_transfer \
  --data-urlencode success_url="https://example.com/success"
```

#### MX

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][currency]"=mxn \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][unit_amount]"=18000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d "payment_method_types[0]"=card \
  -d "payment_method_types[1]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=mx_bank_transfer \
  --data-urlencode success_url="https://example.com/success"
```

### 重定向到 Stripe 托管的银行转账说明页面

> 与银行卡付款不同，进行银行转账时，并不总是将客户重定向到 [success_url](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-success_url)。

*提交* (Submitting an order indicates that the customer intends to pay. Upon submission, the order can no longer be updated and is ready for payment)后，Checkout 表单成功，

- 如果客户余额足够多，足以支付请求的金额，那么付款立即成功，客户被重定向到 [success_url](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-success_url)。
- 如果客户余额足够多，足以支付请求的金额，那么客户会被重定向到 [hosted_instructions_url](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-hosted_instructions_url)。页面上有说明，会指导您的客户完成转账。

Stripe 允许在[品牌设置](https://dashboard.stripe.com/account/branding)页面自定义面向客户的用户界面。下列品牌设置项可应用到托管的说明页面：

- **图标**——您的品牌图片及公开的商家名称
- **品牌颜色**——用作背景颜色

### 履行订单

由于银行转账是一种*延迟通知型支付方式* (A payment method that can't immediately return payment status when a customer attempts a transaction (for example, ACH debits). Businesses commonly hold an order in a pending state until payment is successful with these payment methods)，因此您需要用一种方式（例如 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests)）来监测付款状态并处理订单*履行* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)情况。了解有关[设置 Webhook 和履行订单](https://docs.stripe.com/checkout/fulfillment.md)的更多信息。

付款状态变化时会发送以下事件：

| 事件名称                                                                                                                                         | 描述                                                     | 后续步骤          |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)                             | 客户成功提交了 Checkout 表单，然后被重定向到 `hosted_instructions_url`。 | 等待客户完成银行转账    |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | 客户已成功进行银行转账。`PaymentIntent` 状态变为 `succeeded`。          | 履行客户购买的商品或服务。 |

## Optional: 发送付款说明邮件

您可以从[管理平台](https://dashboard.stripe.com/settings/emails)启用银行转账付款说明邮件。启用付款说明邮件后，当以下情况发生时，Stripe 会给客户发送邮件：

- PaymentIntent 已确认，但客户余额不足。
- 客户发送了银行转账，但资金不足，无法完成付款。

银行转账付款说明邮件包含应付金额、用于转账的银行信息以及到 Stripe 托管说明页面的链接。

> 在沙盒中，付款说明邮件只会发送到 Stripe 账户关联的邮件地址。

## 测试您的集成

可以通过用 API、管理平台或一个 Stripe CLI 的 Beta 版本号模拟一笔传入银行转账来测试您的集成。

#### 管理平台

要在*沙盒* (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)中使用管理平台模拟银行转账，请转到管理平台中的客户页面。在**支付方式**下，单击**添加**，然后选择**资金现金余额（仅限测试）**。

#### API

要用 API 模拟银行转账：

#### US

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="REF-4242" \
  -d "amount"="1000" \
  -d "currency"="usd"
```

#### UK

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="REF-4242" \
  -d "amount"="1000" \
  -d "currency"="gbp"
```

#### EU

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="REF-4242" \
  -d "amount"="1000" \
  -d "currency"="eur"
```

#### JP

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "amount"="1000" \
  -d "currency"="jpy"
```

#### MX

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="123456" \
  -d "amount"="1000" \
  -d "currency"="mxn"
```

#### Stripe CLI

要用 Stripe CLI 模拟银行转账：

1. [安装 Stripe CLI](https://docs.stripe.com/stripe-cli.md)。

1. 使用您登录 Stripe 管理平台时所用的同一账户登录 CLI。

   ```bash
   stripe login
   ```

1. 为现有客户模拟一笔传入银行转账。

   #### US

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=DVGBG97TZ6ZV \
     --currency=usd
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

   #### UK

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=DVGBG97TZ6ZV \
     --currency=gbp
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

   #### EU

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=DVGBG97TZ6ZV \
     --currency=eur
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

   #### JP

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1000 \
     --currency=jpy
   ```

   #### MX

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=123456 \
     --currency=mxn
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

## See also

- [Checkout 订单履行](https://docs.stripe.com/checkout/fulfillment.md)
- [自定义 Checkout](https://docs.stripe.com/payments/checkout/customization.md)


# Elements

> This is a Elements for when payment-ui is elements. View the full page at https://docs.stripe.com/payments/bank-transfers/accept-a-payment?payment-ui=elements.

## 设置 Stripe [服务器端]

首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

用我们的官方库从您的应用程序访问 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'
```

## 创建或检索 Customer [服务器端]

要核对每笔银行转账付款，您必须关联一个 [Customer](https://docs.stripe.com/api/customers.md) 对象。如果您有现成的 Customer 对象，则可以跳过这一步。否则，创建一个新的 Customer 对象。

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

## 创建 PaymentIntent [服务器端]

[PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) 是一个用来表示您从客户收款意图的对象，并可用于跟踪整个付款流程中各个阶段的情况。在服务器上创建一个 PaymentIntent，指定想要收取的金额和货币。您还必须填充 PaymentIntent 创建请求的 [customer parameter](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer)。没有客户时，不能在 PaymentIntent 上使用银行转账。

#### 从管理平台管理支付方式

创建 Payment Intent 之前，请确保在管理平台的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)页面中开启**银行转账**。

> 借助[动态支付方式](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)，Stripe 会根据交易金额、货币和支付流程等因素返回符合条件的支付方式。

#### 美国

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

#### 英国

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

#### 欧盟

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

要以本地方式向客户显示 IBAN，您可以通过设置 [`address.country`](https://docs.stripe.com/api/customers/object.md#customer_object-address-country) 属性或[在管理平台中编辑客户](https://docs.stripe.com/invoicing/customer.md#edit-a-customer)来配置客户的国家/地区。

我们支持  的 IBAN 本地化：

- 如果尚未为您的客户配置国家/地区，或其所在国家/地区不支持 IBAN 本地化，系统将默认使用您的 Stripe 账户所属国家/地区。
- 如果您的 Stripe 账户所在的国家不支持 IBAN 本地化，我们将返回 `IE`。

> 目前不能为西班牙 (ES) 创建新的本地化虚拟银行账号。请改用其他 EU VBAN 国家/地区。

#### 日本

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=19000 \
  -d customer="{{CUSTOMER_ID}}" \
  -d currency=jpy \
  -d "automatic_payment_methods[enabled]"=true \
  --data-urlencode return_url="https://example.com/return_url"
```

#### 墨西哥

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

在最新版的 API 中，可以选择性指定 `automatic_payment_methods` 参数，因为 Stripe 会默认开启其功能。

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

#### 手动列出支付方式

要使用 API 手动指定支付方式，请将 `customer_balance` 添加到您的 PaymentIntent 的 [payment method types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) 列表。指定 Customer 的 [id](https://docs.stripe.com/api/customers/object.md#customer_object-id)。

#### 美国

```curl
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[]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=us_bank_transfer
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `us_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

#### 英国

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=gbp \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=gb_bank_transfer
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `gb_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

#### 欧盟

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=eur \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=eu_bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]"=FR
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `eu_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。
- 将 [payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-eu_bank_account-country) 设置为 中的某一个。向客户显示的 IBAN 会根据所选择的国家/地区进行本地化处理。

> 目前不能为西班牙 (ES) 创建新的本地化虚拟银行账号。请改用其他 EU VBAN 国家/地区。

#### 日本

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=19000 \
  -d currency=jpy \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=jp_bank_transfer
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `jp_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

#### 墨西哥

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=mxn \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=mx_bank_transfer
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `mx_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

> 创建付款时始终要指定 `payment_method_types`。您不能将 `customer_balance` 用于[未来的付款](https://docs.stripe.com/payments/save-and-reuse.md)。

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

用 [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/clover/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)，利用自动填充和本地化功能收集客户的完整地址。这有助于确保税款计算达到最高准确性。
- 使用您自己的自定义表单收集地址详情。

一经确认，Stripe 会自动打开一个模态，向客户显示银行转账的详情。

## 向 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;
```

## Optional: 发送付款说明邮件

您可以从[管理平台](https://dashboard.stripe.com/settings/emails)启用银行转账付款说明邮件。启用付款说明邮件后，当以下情况发生时，Stripe 会给客户发送邮件：

- PaymentIntent 已确认，但客户余额不足。
- 客户发送了银行转账，但资金不足，无法完成付款。

银行转账付款说明邮件包含应付金额、用于转账的银行信息以及到 Stripe 托管说明页面的链接。

> 在沙盒中，付款说明邮件只会发送到 Stripe 账户关联的邮件地址。

## 确认 PaymentIntent 成功

PaymentIntent 保持在 `requires_action` 状态，直至资金到达银行账户。资金就位后，PaymentIntent 的状态从 `requires_action` 更新为 `succeeded`。

需设置您的 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 端点后才能开始接收 `payment_intent.partially_funded` 事件。当给 PaymentIntent 部分资金后，状态仍会是 `requires_action`。

您可以[从管理平台添加 webhook](https://dashboard.stripe.com/webhooks/create)。

或者，您可以用 [Webhook Endpoints API](https://docs.stripe.com/api/webhook_endpoints.md) 开始接收 [payment_intent.partially_funded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.partially_funded) 事件。

> [Stripe CLI](https://docs.stripe.com/stripe-cli.md) 不支持触发 Beta API 版本的事件，例如 `payment_intent.partially_funded`。

PaymentIntent 被更新时，付款的充值流程中会发送以下事件：

| 活动                                | 描述                                                                                                                                                     | 后续步骤                                                                                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent.requires_action`  | 客户余额资金不足，不能补齐 PaymentIntent 时，在确认过程中发送，PaymentIntent 变为 `requires_action`。                                                                             | 引导客户发送一笔金额为 `amount_remaining` 的银行转账。                                                                                                                               |
| `payment_intent.partially_funded` | 客户发送了银行转账，并且应用到了 PaymentIntent，但不足以完成付款。客户转账金额不足（由于错误地少付或其银行从中扣留了费用）或剩余的客户余额已应用到此 PaymentIntent 时就可能发生这种情况。部分注入资金的 PaymentIntents 不会提现在您的账户余额上，直至付款完成。 | 引导您的客户用一个新的 `amount_remaining` 再发送一笔银行转账，从而完成付款。如果想通过部分应用资金来完成付款，可以更新 `amount` 并再次 [confirm](https://docs.stripe.com/api/payment_intents/confirm.md) PaymentIntent。 |
| `payment_intent.succeeded`        | 客户付款成功。                                                                                                                                                | 履行客户购买的商品或服务。                                                                                                                                                       |

> 当您更改有部分资金的 PaymentIntent 的金额时，资金将返回到客户余额。如果有其他未完成的 PaymentIntents，则 Stripe 自动提供这些资金。如果客户配置的是手动对账，那么您需要再次 [apply the funds](https://docs.stripe.com/api/payment_intents/apply_customer_balance.md)。

建议[用 Webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) 来确认成功收款操作，并通知客户付款已完成。

### 示例代码

#### Ruby

```ruby
require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.requires_action'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # The payment intent was not fully funded due to insufficient funds
    # on the customer balance. Define and call a method to handle the payment intent.
    # handle_payment_intent_requires_action(payment_intent)
  when 'payment_intent.partially_funded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the payment intent being partially funded.
    # handle_payment_intent_partially_funded(payment_intent)
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

### 在管理平台查看待处理的付款

您可以通过将**等待资金**筛选器应用到**状态**来在[管理平台](https://dashboard.stripe.com/payments)中查看所有待处理的银行转账 PaymentIntents。

## 测试您的集成

可以通过用 API、管理平台或一个 Stripe CLI 的 Beta 版本号模拟一笔传入银行转账来测试您的集成。

#### 管理平台

要在*沙盒* (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)中使用管理平台模拟银行转账，请转到管理平台中的客户页面。在**支付方式**下，单击**添加**，然后选择**资金现金余额（仅限测试）**。

#### API

要用 API 模拟银行转账：

#### US

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="REF-4242" \
  -d "amount"="1000" \
  -d "currency"="usd"
```

#### UK

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="REF-4242" \
  -d "amount"="1000" \
  -d "currency"="gbp"
```

#### EU

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="REF-4242" \
  -d "amount"="1000" \
  -d "currency"="eur"
```

#### JP

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "amount"="1000" \
  -d "currency"="jpy"
```

#### MX

```bash
curl https://api.stripe.com/v1/test_helpers/customers/{{CUSTOMER_ID}}/fund_cash_balance \
  -X POST \
  -u <<YOUR_SECRET_KEY>>: \
  -d "reference"="123456" \
  -d "amount"="1000" \
  -d "currency"="mxn"
```

#### Stripe CLI

要用 Stripe CLI 模拟银行转账：

1. [安装 Stripe CLI](https://docs.stripe.com/stripe-cli.md)。

1. 使用您登录 Stripe 管理平台时所用的同一账户登录 CLI。

   ```bash
   stripe login
   ```

1. 为现有客户模拟一笔传入银行转账。

   #### US

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=DVGBG97TZ6ZV \
     --currency=usd
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

   #### UK

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=DVGBG97TZ6ZV \
     --currency=gbp
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

   #### EU

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=DVGBG97TZ6ZV \
     --currency=eur
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

   #### JP

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1000 \
     --currency=jpy
   ```

   #### MX

   ```bash
   stripe test_helpers customers fund_cash_balance "{{CUSTOMER_ID}}" \
     --amount=1099 \
     --reference=123456 \
     --currency=mxn
   ```

   `reference` 参数是可选的，它模拟的是客户为银行转账的参考字段填写的值。

## 处理临时性的可用性问题

以下错误代码表明支付方式的可用性出现了临时性的问题：

| 代码                                   | 描述                                                                          | 处理                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `payment_method_rate_limit_exceeded` | 该支付方式的连续请求太多，其限制比 [API 范围的速率限制](https://docs.stripe.com/rate-limits.md)更严格。 | 当您的许多客户在同一时段试图使用相同的支付方式时（例如，您的网站进行持续销售期间），多个 API 请求可能会持续发生这些错误。这种情况下，请让您的客户选择另外的支付方式。 |

> 如果您预计一般情况下会用量激增或有即将要举行的大型活动，请在知道后立即联系我们。


# 直接 API

> This is a 直接 API for when payment-ui is direct-api. View the full page at https://docs.stripe.com/payments/bank-transfers/accept-a-payment?payment-ui=direct-api.

## 设置 Stripe [服务器端]

首先，您需要有一个 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

用我们的官方库从您的应用程序访问 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'
```

## 创建或检索 Customer [服务器端]

要核对每笔银行转账付款，您必须关联一个 [Customer](https://docs.stripe.com/api/customers.md) 对象。如果您有现成的 Customer 对象，则可以跳过这一步。否则，创建一个新的 Customer 对象。

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

## 创建并确认 PaymentIntent [服务器端]

[PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) 是一个用来表示您从客户收款意图的对象，并可用于跟踪整个付款流程中各个阶段的情况。在服务器上创建并确认一个 PaymentIntent，指定想要收取的金额和货币。您还必须填充 PaymentIntent 创建请求的[客户参数](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer)。没有客户时，银行转账不能在 PaymentIntents 上使用。

#### 从管理平台管理支付方式

创建 Payment Intent 之前，请确保在管理平台的[支付方式设置](https://dashboard.stripe.com/settings/payment_methods)页面中开启**银行转账**。

> 借助[动态支付方式](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)，Stripe 会根据交易金额、货币和支付流程等因素返回符合条件的支付方式。

#### 美国

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

#### 英国

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d customer="{{CUSTOMER_ID}}" \
  -d currency=gbp \
  -d "automatic_payment_methods[enabled]"=true \
  --data-urlencode return_url="https://example.com/return_url" \
  -d "payment_method_data[type]"=customer_balance \
  -d confirm=true
```

#### 欧盟

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d customer="{{CUSTOMER_ID}}" \
  -d currency=eur \
  -d "automatic_payment_methods[enabled]"=true \
  --data-urlencode return_url="https://example.com/return_url" \
  -d "payment_method_data[type]"=customer_balance \
  -d confirm=true
```

要以本地方式向客户显示 IBAN，您可以通过设置 [`address.country`](https://docs.stripe.com/api/customers/object.md#customer_object-address-country) 属性或[在管理平台中编辑客户](https://docs.stripe.com/invoicing/customer.md#edit-a-customer)来配置客户的国家/地区。

我们支持  的 IBAN 本地化：

- 如果尚未为您的客户配置国家/地区，或其所在国家/地区不支持 IBAN 本地化，系统将默认使用您的 Stripe 账户所属国家/地区。
- 如果您的 Stripe 账户所在的国家不支持 IBAN 本地化，我们将返回 `IE`。

> 目前不能为西班牙 (ES) 创建新的本地化虚拟银行账号。请改用其他 EU VBAN 国家/地区。

#### 日本

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=19000 \
  -d customer="{{CUSTOMER_ID}}" \
  -d currency=jpy \
  -d "automatic_payment_methods[enabled]"=true \
  --data-urlencode return_url="https://example.com/return_url" \
  -d "payment_method_data[type]"=customer_balance \
  -d confirm=true
```

#### 墨西哥

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d customer="{{CUSTOMER_ID}}" \
  -d currency=mxn \
  -d "automatic_payment_methods[enabled]"=true \
  --data-urlencode return_url="https://example.com/return_url" \
  -d "payment_method_data[type]"=customer_balance \
  -d confirm=true
```

在最新版的 API 中，可以选择性指定 `automatic_payment_methods` 参数，因为 Stripe 会默认开启其功能。

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

#### 手动列出支付方式

要使用 API 手动指定支付方式，请将 `customer_balance` 添加到您的 PaymentIntent 的 [payment method types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) 列表。指定 Customer 的 [id](https://docs.stripe.com/api/customers/object.md#customer_object-id)。

#### 美国

```curl
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[]"=customer_balance \
  -d "payment_method_data[type]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=us_bank_transfer \
  -d confirm=true
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `us_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

#### 英国

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=gbp \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_data[type]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=gb_bank_transfer \
  -d confirm=true
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `gb_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

#### 欧盟

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=eur \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_data[type]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=eu_bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]"=FR \
  -d confirm=true
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `eu_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。
- 将 [payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-eu_bank_account-country) 设置为 中的某一个。向客户显示的 IBAN 会根据所选择的国家/地区进行本地化处理。

> 目前不能为西班牙 (ES) 创建新的本地化虚拟银行账号。请改用其他 EU VBAN 国家/地区。

#### 日本

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=19000 \
  -d currency=jpy \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_data[type]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=jp_bank_transfer \
  -d confirm=true
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `jp_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

#### 墨西哥

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=mxn \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=customer_balance \
  -d "payment_method_data[type]"=customer_balance \
  -d "payment_method_options[customer_balance][funding_type]"=bank_transfer \
  -d "payment_method_options[customer_balance][bank_transfer][type]"=mx_bank_transfer \
  -d confirm=true
```

如果客户的余额足够高，足以完成付款，则 PaymentIntent 立即成功，显示 `succeeded` 状态。当客户不小心多付时，他们可以累算余额，这在银行转账中很常见。您必须要在[您所在地的特定时间段内确认客户余额](https://docs.stripe.com/payments/customer-balance/reconciliation.md)。

- 将 `bank_transfer` 用作 [funding_type](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-funding_type)，指定客户余额不足以完成转账时该如何做。
- 将 `mx_bank_transfer` 用作 [bank_transfer[type]](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-type)，指定可用于支付资金的银行转账类型。

> 创建付款时始终要指定 `payment_method_types`。您不能将 `customer_balance` 用于[未来的付款](https://docs.stripe.com/payments/save-and-reuse.md)。

## 引导客户完成银行转账 [客户端]

如果客户的余额不足以支付请求的金额，则 PaymentIntent 显示 `requires_action` 状态。响应中有一个 `next_action` 字段，包含 `display_bank_transfer_instructions` 的一个 `type` 值。`next_action[display_bank_transfer_instructions]` 散列中包含向客户显示的信息，以便其完成银行转账。为确保资金结算，请指示您的客户使用所提供的确切信息，特别是账户名和账号（如果适用）。

> 在*真实模式* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments)下，Stripe 为每个客户提供唯一一套银行转账信息。相反，在测试环境中，Stripe 向所有客户提供的都是无效的银行转账详情。与真实模式不同，这些无效的详情可能并不总是唯一。

#### 美国

| 字段                                                                                                                                                                            | 描述                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-type)                                         | 使用的银行转账类型。美国的类型必须为 `us_bank_transfer`。                                                      |
| [参考](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-reference)                                    | 识别银行转账的唯一参考代码。引导客户在其银行转账的参考字段中包含此代码。                                                        |
| [amount_remaining](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-amount_remaining)               | 完成付款所需转的剩余金额。引导客户转此金额。如果客户余额中之前存在的资金已应用到 PaymentIntent 或如果客户少付了，则此金额可能不同于 PaymentIntent 金额。 |
| [货币](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-currency)                                     | 剩余金额的币种。                                                                                    |
| [financial_addresses](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions)                             | 美国银行账户金融地址列表。类型包含 `aba` 和 `swift`。查看下方详情。                                                   |
| [hosted_instructions_url](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-hosted_instructions_url) | 一个指向托管页面的链接，引导客户完成转账。                                                                       |

#### aba 散列

`aba` 散列示例：

```json
{
  "aba": {
    "account_number": "111222333444",
    "bank_name": "Wells Fargo Bank, NA",
    "routing_number": "444555666"
  },
  "supported_networks": [
    "ach",
    "domestic_wire_us"
  ],
  "type": "aba"
}
```

| 字段                   | 值                              | 描述           |
| -------------------- | ------------------------------ | ------------ |
| `type`               | `aba`                          | 金融机构地址类型。    |
| `supported_networks` | - `ach`
  - `domestic_wire_us` | 该地址支持的卡组织列表。 |
| `aba.account_number` | 111222333444                   | ABA 账号。      |
| `aba.routing_number` | 444555666                      | ABA 路径号码。    |
| `aba.bank_name`      | Wells Fargo Bank, NA           | 银行名称。        |

#### swift 散列

`swift` 散列示例：

```json
{
  "swift": {
    "account_number": "111222333444",
    "bank_name": "Wells Fargo Bank, NA",
    "swift_code": "AAAA-BB-CC-123"
  },
  "supported_networks": [
    "swift"
  ],
  "type": "swift"
}
```

| 字段                     | 值                    | 描述           |
| ---------------------- | -------------------- | ------------ |
| `type`                 | `swift`              | 金融机构地址类型。    |
| `supported_networks`   | - `swift`            | 该地址支持的卡组织列表。 |
| `swift.account_number` | 111222333444         | SWIFT 账号。    |
| `swift.swift_code`     | AAAA-BB-CC-123       | SWIFT 代码。    |
| `swift.bank_name`      | Wells Fargo Bank, NA | 银行名称。        |

#### 结算时间

在引导您的客户用您提供的信息在其银行发起转账后，可能需要长达 5 天才能完成转账。结算时间取决于转账到达 Stripe 的银行通道：

- ACH 转账为 1-3 个工作日到账。
- 国内电汇 (Fedwire) 当天到账（取决于转账是否是在银行下班前发出）。
- 国际电汇 (SWIFT) 为 1-5 个工作日到账。

#### 英国

| 字段                                                                                                                                                                            | 描述                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-type)                                         | 使用的银行转账类型。英国的类型必须为 `gb_bank_transfer`。                                                      |
| [参考](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-reference)                                    | 识别银行转账的唯一参考代码。引导客户在其银行转账的参考字段中包含此代码。                                                        |
| [amount_remaining](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-amount_remaining)               | 完成付款所需转的剩余金额。引导客户转此金额。如果客户余额中之前存在的资金已应用到 PaymentIntent 或如果客户少付了，则此金额可能不同于 PaymentIntent 金额。 |
| [货币](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-currency)                                     | 剩余金额的币种。                                                                                    |
| [financial_addresses](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions)                             | 英国银行账户金融地址列表。类型包含 `sort_code`。查看下方详情。                                                       |
| [hosted_instructions_url](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-hosted_instructions_url) | 一个指向托管页面的链接，引导客户完成转账。                                                                       |

### sort_code 散列

`sort_code` 散列示例：

```json
{
  "sort_code": {
    "account_holder_name": "Demo Test Inc.",
    "account_number": "98765432",
    "sort_code": "200000"
  },
  "supported_networks": [
    "bacs",
    "fps"
  ],
  "type": "sort_code"
}
```

| 字段                                                                                                                                                                                                            | 值                  | 描述                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-type)                                                     | `sort_code`        | 金融机构地址类型。         |
| [supported_networks](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-supported_networks)                       | - `bacs`
  - `fps` | 该地址支持的卡组织列表。      |
| [sort_code.account_number](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-sort_code-account_number)           | 98765432           | 5 位数账号。           |
| [sort_code.sort_code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-sort_code-sort_code)                     | 200000             | 6 位数分类代码。         |
| [sort_code.account_holder_name](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-sort_code-account_holder_name) | Demo Test Inc.     | 拥有该银行账户的个人或公司的名称。 |

#### 结算时间

在引导您的客户用您提供的信息在其银行发起转账后，可能需要长达 5 天才能完成转账。结算时间取决于转账到达 Stripe 的银行通道：

- FPS 转账在 15 分钟内。
- BACS 转账 5 天内到账。

> 目前不支持通过 [CHAPS](https://www.bankofengland.co.uk/payment-and-settlement/chaps) 支付组织发送银行转账。

#### 欧盟

| 字段                                                                                                                                                                            | 描述                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-type)                                         | 使用的银行转账类型。欧盟的类型必须为 `eu_bank_transfer`。                                                      |
| [参考](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-reference)                                    | 识别银行转账的唯一参考代码。引导客户在其银行转账的参考字段中包含此代码。                                                        |
| [amount_remaining](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-amount_remaining)               | 完成付款所需转的剩余金额。引导客户转此金额。如果客户余额中之前存在的资金已应用到 PaymentIntent 或如果客户少付了，则此金额可能不同于 PaymentIntent 金额。 |
| [货币](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-currency)                                     | 剩余金额的币种。                                                                                    |
| [financial_addresses](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions)                             | 欧盟银行账户金融地址列表。类型包含 `iban`。查看下方详情。                                                            |
| [hosted_instructions_url](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-hosted_instructions_url) | 一个指向托管页面的链接，引导客户完成转账。                                                                       |

### iban 散列

`iban` 散列示例：

```json
{
  "iban": {
    "account_holder_name": "Demo Test Inc.",
    "bic": "CITINL2XXXX",
    "country": "NL",
    "iban": "NL40CITI7000799556	"
  },
  "supported_networks": [
    "sepa"
  ],
  "type": "iban"
}
```

| 字段                                                                                                                                                                                                  | 值                  | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-type)                                           | `iban`             | 金融机构地址类型。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [supported_networks](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-supported_networks)             | - `sepa`           | 该地址支持的卡组织列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [iban.iban](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-iban-iban)                               | NL40CITI7000799556 | 客户需要付款到的 IBAN。

  如果您从[管理平台](https://dashboard.stripe.com/settings/payment_methods)中管理支付方式，则根据客户[国家](https://docs.stripe.com/api/customers/object.md#customer_object-country)或您的 Stripe 账户的国家选择 IBAN 的国家/地区。

  如果您用 [payment_method_types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) 参数手动列出支付方式，则根据请求中传递的[国家](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-customer_balance-bank_transfer-eu_bank_transfer-country)参数选择 IBAN 的国家。 |
| [iban.bic](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-iban-bic)                                 | CITINL2XXXX        | 此 IBAN 的 BIC。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [iban.country](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-iban-country)                         | `NL`               | 资金要转往的银行账户的两字母国家代码。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [iban.account_holder_name](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-iban-account_holder_name) | Demo Test Inc.     | 拥有该银行账户的个人或公司的名称。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

#### 结算时间

对于国内转账，请让您的客户使用您提供的详细信息发起欧洲单一欧元支付区 (SEPA) 即时转账（在可用的情况下）。资金通常在数秒内到账，最迟 30 分钟内到账。若在周末、银行假日转账，或发送方银行无法通过即时转账系统处理支付，则结算时间可能会延长。在这些情况下，转账将作为标准的 SEPA 支付进行处理。

> 目前，接收国际欧元转账功能处于预览阶段。如需获取早期访问权限，请联系 [sepa-bank-transfers-beta@stripe.com](mailto:sepa-bank-transfers-beta@stripe.com)。

#### 日本

| 字段                                                                                                                                                                            | 描述                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-type)                                         | 使用的银行转账类型。日本的类型必须为 `jp_bank_transfer`。                                                      |
| [参考](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-reference)                                    | 此字段未使用。                                                                                     |
| [amount_remaining](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-amount_remaining)               | 完成付款所需转的剩余金额。引导客户转此金额。如果客户余额中之前存在的资金已应用到 PaymentIntent 或如果客户少付了，则此金额可能不同于 PaymentIntent 金额。 |
| [货币](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-currency)                                     | 剩余金额的币种。                                                                                    |
| [financial_addresses](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses)         | 日本银行账户金融地址列表。类型包含 `zengin`。查看下方详情。                                                          |
| [hosted_instructions_url](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-hosted_instructions_url) | 一个指向托管页面的链接，引导客户完成转账。                                                                       |

### zengin 散列

`zengin` 散列示例：

```json
{
  "zengin": {
    "account_holder_name": "ストライプジャパン（カ　シュウノウダイコウ",
    "account_number": "1234567",
    "account_type": "futsu",
    "bank_code": "0009",
    "bank_name": "三井住友銀行",
    "branch_code": "950",
    "branch_name": "東京第二"
  },
  "supported_networks": [
    "zengin"
  ],
  "type": "zengin"
}
```

| 字段                                                                                                                                                                                                      | 值                     | 描述           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------ |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-type)                                               | `zengin`              | 金融机构地址类型。    |
| [supported_networks](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-supported_networks)                 | - `zengin`            | 该地址支持的卡组织列表。 |
| [zengin.bank_code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-bank_code)                     | 0009                  | 4 位数银行代码。    |
| [zengin.bank_name](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-bank_name)                     | 三井住友銀行                | 银行名称。        |
| [zengin.branch_code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-branch_code)                 | 950                   | 3 位数分行代码。    |
| [zengin.branch_name](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-branch_name)                 | 東京第二                  | 分行名称。        |
| [zengin.account_type](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-account_type)               | `futsu`, `toza`       | 账户类型。        |
| [zengin.account_holder_name](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-account_holder_name) | ストライプジャパン（カ　シュウノウダイコウ | 账户持有人姓名。     |
| [zengin.account_number](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-zengin-account_number)           | 1234567               | 7 位数账号。      |

#### 结算时间

引导您的客户用您提供的信息在其银行发起转账。

在营业时间内进行的转账将在当天到账。营业时间以外进行的转账将在下一工作日到账。

#### MX

| 字段                                                                                                                                                                            | 描述                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-type)                                         | 使用的银行转账类型。墨西哥的类型必须为 `mx_bank_transfer`。                                                     |
| [参考](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-reference)                                    | 识别银行转账的唯一参考代码。引导客户在其银行转账的参考字段中包含此代码。                                                        |
| [amount_remaining](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-amount_remaining)               | 完成付款所需转的剩余金额。引导客户转此金额。如果客户余额中之前存在的资金已应用到 PaymentIntent 或如果客户少付了，则此金额可能不同于 PaymentIntent 金额。 |
| [货币](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-currency)                                     | 剩余金额的币种。                                                                                    |
| [financial_addresses](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions)                             | 墨西哥银行账户金融地址列表。类型包括 `spei`。查看下方详情。                                                           |
| [hosted_instructions_url](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-hosted_instructions_url) | 一个指向托管页面的链接，引导客户完成转账。                                                                       |

### spei 散列

`spei` 散列示例：

```json
{
  "spei": {
    "bank_code": "002",
    "bank_name": "BANAMEX",
    "clabe": "002180650612345670"
  },
  "supported_networks": [
    "spei"
  ],
  "type": "spei"
}
```

| 字段                                                                                                                                                                                      | 值                  | 描述             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------- |
| [类型](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-type)                               | `spei`             | 金融机构地址类型。      |
| [supported_networks](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-supported_networks) | - `spei`           | 该地址支持的卡组织列表。   |
| [spei.clabe](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-spei-clabe)                 | 002180650612345670 | 18 位 CLABE 账号。 |
| [spei.bank_code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-spei-bank_code)         | 002                | 3 位数银行代码。      |
| [spei.bank_name](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-display_bank_transfer_instructions-financial_addresses-spei-bank_name)         | BANAMEX            | 银行机构的简短名称      |

引导您的客户用您提供的信息在其银行发起转账。

无论是否为银行工作日，大多数付款预计均会在 10 分钟内到账。

## 确认 PaymentIntent 成功

PaymentIntent 保持在 `requires_action` 状态，直至资金到达银行账户。资金就位后，PaymentIntent 的状态从 `requires_action` 更新为 `succeeded`。

需设置您的 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 端点后才能开始接收 `payment_intent.partially_funded` 事件。

您可以[从管理平台添加 webhook](https://dashboard.stripe.com/webhooks/create)。

或者，您可以用 [Webhook Endpoints API](https://docs.stripe.com/api/webhook_endpoints.md) 开始接收 [payment_intent.partially_funded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.partially_funded) 事件。

当我们更新 PaymentIntent 时，Stripe 会在支付流程过程中发送以下事件。

| 事件                                | 描述                                                                                                                                                                                          | 后续步骤                                                                                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent.requires_action`  | 在确认过程中，若客户余额资金不足，无法结清 PaymentIntent，则 PaymentIntent 会转为 `requires_action` 状态。如果在确认时客户现金余额已自动应用于该 PaymentIntent，但金额不足以完全覆盖 PaymentIntent 的 `amount`，Stripe 会触发此事件，并附带准确的 `amount_remaining`。 | 引导客户发送一笔金额为 `amount_remaining` 的银行转账。                                                                                                                       |
| `payment_intent.partially_funded` | 客户发送了一笔银行转账，该转账已应用于 PaymentIntent，但金额不足以完成付款。如果客户在您确认 `PaymentIntent` 后转账金额不足，就会发生这种情况。这可能是由于少付或客户银行收取的费用。部分出资的 PaymentIntent 在付款完成前不会反映在您的账户余额中。                                           | 引导您的客户用新的 `amount_remaining` 再发送一笔银行转账，从而完成付款。如果想通过部分应用资金来完成付款，可以更新 `amount` 并再次[确认](https://docs.stripe.com/api/payment_intents/confirm.md) PaymentIntent。 |
| `payment_intent.succeeded`        | 客户付款成功。                                                                                                                                                                                     | 履行客户购买的商品或服务。                                                                                                                                               |

如需监听所有与部分付款相关的事件，请同时监听 `requires_action` 和 `partially_funded`。当确认后仍需资金时，Stripe 会触发 `requires_action`。当后续收到客户支付的额外资金，但该资金仍不足以完全覆盖剩余金额时，我们会触发 `partially_funded`。

> 当您更改有部分资金的 PaymentIntent 的金额时，资金将返回到客户余额。如果有其他未完成的 PaymentIntent，则 Stripe 自动提供这些资金。如果客户配置的是手动对账，则您需要再次[应用资金](https://docs.stripe.com/api/payment_intents/apply_customer_balance.md)。

我们建议[用 Webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) 来确认成功收款操作，并通知客户付款已完成。

### 示例代码

#### Ruby

```ruby
require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.requires_action'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # The payment intent was not fully funded due to insufficient funds
    # on the customer balance. Define and call a method to handle the payment intent.
    # handle_payment_intent_requires_action(payment_intent)
  when 'payment_intent.partially_funded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the payment intent being partially funded.
    # handle_payment_intent_partially_funded(payment_intent)
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

### 在管理平台查看待处理的付款

您可以通过将**等待资金**筛选器应用到**状态**来在[管理平台](https://dashboard.stripe.com/payments)中查看所有待处理的银行转账 PaymentIntents。

## 测试您的集成

您可以通过在管理平台中或通过 HTTP 请求模拟传入银行转账来测试您的集成。

### 使用管理平台

要在*沙盒* (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)中使用管理平台模拟银行转账，请转到管理平台中的客户页面。在**支付方式**下，单击**添加**，然后选择**资金现金余额（仅限测试）**。

### 使用 Stripe API

您可以发起一个 API 调用来模拟一笔银行转账。

#### 美国

```curl
curl https://api.stripe.com/v1/test_helpers/customers/cus_xxxxxxxxx/fund_cash_balance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d reference=REF-4242
```

You can simulate a reversal by prefixing the `reference` parameter with `reversal_` (for example, `reversal_123`).

#### 英国

```curl
curl https://api.stripe.com/v1/test_helpers/customers/cus_xxxxxxxxx/fund_cash_balance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=gbp \
  -d reference=REF-4242
```

#### 欧盟

```curl
curl https://api.stripe.com/v1/test_helpers/customers/cus_xxxx/fund_cash_balance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=eur \
  -d reference=REF-4242
```

#### 日本

```curl
curl https://api.stripe.com/v1/test_helpers/customers/cus_xxxx/fund_cash_balance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=10000 \
  -d currency=jpy
```

#### MX

```curl
curl https://api.stripe.com/v1/test_helpers/customers/cus_xxxx/fund_cash_balance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=mxn \
  -d reference=123456
```

## 处理临时性的可用性问题

以下错误代码表明支付方式的可用性出现了临时性的问题：

| 代码                                   | 描述                                                                          | 处理                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `payment_method_rate_limit_exceeded` | 该支付方式的连续请求太多，其限制比 [API 范围的速率限制](https://docs.stripe.com/rate-limits.md)更严格。 | 当您的许多客户在同一时段试图使用相同的支付方式时（例如，您的网站进行持续销售期间），多个 API 请求可能会持续发生这些错误。这种情况下，请让您的客户选择另外的支付方式。 |

> 如果您预计一般情况下会用量激增或有即将要举行的大型活动，请在知道后立即联系我们。

## Optional: 从客户那里收集支付方式选项

如果需要，在您的网站上收集客户的首选充值类型，并用 [Stripe.js](https://docs.stripe.com/js.md) 的 [confirmCustomerBalancePayment](https://docs.stripe.com/js/payment_intents/confirm_customer_balance_payment) 方式确认付款意图。

显示一个 HTML 表单，以收集客户首选的银行转账充值详情。用该输入信息生成 `payment_method_options`。

查看 [JS 参考文档](https://docs.stripe.com/js/payment_intents/confirm_customer_balance_payment)中可用的 `payment_method_options` parameters for `confirmCustomerBalancePayment` 的完整列表。

请看此用例：如果您是爱尔兰商家，不确定客户是哪个国家的，则可以创建一个 `PaymentIntent`，先将 `payment_method_options[customer_balance][bank_transfer][eu_bank_transfer][country]` 设置为 ‘IE’。然后用 [confirmCustomerBalancePayment](https://docs.stripe.com/js/payment_intents/confirm_customer_balance_payment) 方式，根据用户输入更新国家。

### 示例代码

```javascript
const {paymentIntent, error} = await stripe.confirmCustomerBalancePayment(
  '{PAYMENT_INTENT_CLIENT_SECRET}',
  {
    payment_method: {
      customer_balance: {
      },
    },
    payment_method_options: {
      customer_balance: {
        funding_type: 'bank_transfer',
        bank_transfer: {
          type: 'eu_bank_transfer',
          eu_bank_transfer: {
            country: 'FR',
          }
        },
      },
    },
  },
  {
    handleActions: false,
  }
);
if (error) {
  // Inform the customer that there was an error.
} else if (paymentIntent.status === 'requires_payment_method') {
  // If `payment_method_options.funding_type` wasn't set this
  // is where you would need to handle the insufficient customer
  // balance state.
} else if (paymentIntent.status === 'requires_action') {
  // If the current customer balance is insufficient to cover
  // the amount, and you've passed
  // `payment_method_options.funding_type` for funding the
  // customer balance, you can display the bank transfer
  // instructions to your user.
  if (paymentIntent.next_action.type === 'display_bank_transfer_instructions') {
    // Bank transfer details can be found under:
    // paymentIntent.next_action.display_bank_transfer_instructions
  }
}
```

## Optional: 发送付款说明邮件

您可以从[管理平台](https://dashboard.stripe.com/settings/emails)启用银行转账付款说明邮件。启用付款说明邮件后，当以下情况发生时，Stripe 会给客户发送邮件：

- PaymentIntent 已确认，但客户余额不足。
- 客户发送了银行转账，但资金不足，无法完成付款。

银行转账付款说明邮件包含应付金额、用于转账的银行信息以及到 Stripe 托管说明页面的链接。

> 在沙盒中，付款说明邮件只会发送到 Stripe 账户关联的邮件地址。