# SetupIntent、PaymentMethod、BankAccount を使用する

プラットフォーム向け金融口座で資金移動を設定します。

> #### Accounts v2 API 互換性
> 
> Accounts v2 API は Financial Accounts ワークフローをサポートしていません。Accounts v2 で作成されたアカウントがある場合は、Accounts v1 を使用して `treasury` と `card_issuing` の機能を管理できます。詳細については、[顧客として Account を使用する](https://docs.stripe.com/connect/use-accounts-as-customers.md)を参照してください。

[PaymentMethod](https://docs.stripe.com/payments/payment-methods.md#payment-method-object) オブジェクトを使用して、将来の使用に備えてアメリカに拠点を置く銀行口座のアカウント認証情報を保存できます。`PaymentMethod` を作成すると、同じオブジェクトを繰り返し使用して、金融口座の入出金を行うことができます。ユースケースに応じて、`PaymentMethod` を[Customer (顧客)](https://docs.stripe.com/api/customers.md) オブジェクトまたはStripe アカウントのいずれかに関連付けることができます。

- 支払い方法を、サードパーティーへのアウトバウンド支払いに使用するには、`PaymentMethod` を `Customer` オブジェクトに関連付けします。
- 支払い方法を、Stripe アカウントと同じビジネスに属する外部口座間のインバウンド送金またはアウトバウンド送金に使用する場合には、`PaymentMethod` を連結アカウントまたはプラットフォームアカウントに関連付けます。

> `Customer` オブジェクトは、外部銀行口座の所有者を表す第三者 (法人) を定義します。

以前に [BankAccount](https://docs.stripe.com/ach-deprecated.md) オブジェクトを使用して、Stripe で顧客の支払い詳細を収集したことがある場合は、これらのリクエストで、`BankAccount` の代わりに `PaymentMethod` を使用できます。`InboundTransfers` の場合、このケースでは、`BankAccount` `status` の値は `verified` である必要があります。全機能をご利用いただくために、可能な限り `PaymentMethods` のご使用をお勧めします。

場合によっては、ACH 送金の受取側の銀行から Stripe に口座情報 (口座番号や金融番号など) の変更が通知されることがあります。`PaymentMethod` または `BankAccount` オブジェクトに関連付けられている口座の通知を受け取ると、自動的にオブジェクトを更新します。詳細については、[ACH NOC および SEC の取り扱い](https://docs.stripe.com/financial-accounts/connect/moving-money/noc-sec-handling.md) をご覧ください。

## SetupIntent を作成して us_bank_account の詳細を保存する

[SetupIntents](https://docs.stripe.com/payments/setup-intents.md) を使用すると、Stripe API の資金移動エンドポイントで使用するための支払い方法を設定できます。`SetupIntents` を使用し、顧客やアカウントの認証情報を支払い方法として保存して、それを使用する予定のオブジェクトに合わせて最適化します。たとえば、アメリカの銀行口座を設定する際に、インバウンド送金を使用してその外部口座から引き落としを行う予定の場合、銀行口座を確認する必要があります。Stripe は、その設定プロセス全体を通じて `SetupIntent` オブジェクトを更新します。

以下の例では、双方向への資金移動が可能な銀行口座を持つ `SetupIntent` を使用しています。支払いの作成と銀行口座の確認のために支払い方法を設定する方法の詳細については、[ACH ダイレクトデビットによる将来の支払いに備えて詳細を保存する](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md)ガイドをご覧ください。`SetupIntents` で金融口座の資金を管理するするための支払い方法を設定する際には、以下のフィールドが重要です。

- [flow_directions](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-flow_directions): この配列は、支払い方法のフローの方向性を定義します。設定可能な値は `inbound` と `outbound` で、その支払い方法が金融口座で出金または入金、あるいはその両方向で資金を移動できるかどうかを示します。また、既存の支払い方法を双方向として設定することもできます。
- [attach_to_self](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-attach_to_self): この支払い方法をコンテキスト内の `Account` オブジェクトに関連付けるかどうかを示すブール値フラグ。この値を true に設定すると、アカウントに関連付けられた支払い方法を作成し、インバウンド送金やアウトバウンド送金など、このアカウントが保有する資金移動フローを管理できます。
- [customer](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-confirm): 設定完了時に支払い方法が関連付けられる `Customer` オブジェクトの ID。`Customer` に関連付けられた支払い方法を、アウトバウンド支払いで使用して、サードパーティーや顧客に送金できます。また、これらの支払い方法を Stripe Payments `PaymentIntents` で使用して資金を受け取ることもできます。顧客に関連付けられた支払い方法を作成する際には、`attach_to_self` 属性を false に設定するか、ブランクのままにする必要があります。

### 権限

‘inbound’ フロー方向 (`InboundTransfers` など) の支払い方法を使用するには、[アカウント所有者から許可](https://docs.stripe.com/payments/setup-intents.md#mandates)を得る必要があります。この同意書 (`Mandate` オブジェクト) を事前に作成し、それを支払い方法と関連付けしておくことで、それ以降の支払い方法への請求が可能になります。

外部口座から資金を引き落とす方法を示す規約を Web サイトおよびアプリに追加し、連結アカウントがオプトインできるようにします。規約には、少なくとも以下の内容が含まれている必要があります。

- 連結アカウントの代わりに 1 回の引き落としまたは一連の引き落としを開始することについての連結アカウントからの許可
- 予測される引き落とし頻度 (1 回限りまたは継続)
- 引き落とし金額の決定方法

インバウンド送金では、アメリカの外部の銀行口座から引き落としをするには同意書が必要ですが、アウトバウンド送金またはアウトバウンド支払いでの銀行口座への送金には必要ありません。

### SetupIntent を作成する

`SetupIntent` を作成するには、`payment_method` パラメーターで既存の支払い方法を使用するか、インラインの `payment_method_data` パラメーターを使用して新しい認証情報を指定する必要があります。

`POST /v1/setup_intents` を使用して `SetupIntent` を作成します。

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "payment_method={{PAYMENTMETHOD_ID}}"
```

成功するとレスポンスで、新しく作成された `SetupIntent` オブジェクトが返されます。

#### JSON (コメント付き)

```json
{
  // ID of the Customer to attach the resulting PaymentMethod to
  "customer": "{{CUSTOMER_ID}}",
  "attach_to_self": false,
  // Configure what direction of funds flows this PaymentMethod will support.
  "flow_directions": ["inbound", "outbound"],
 // US Bank Account credentials
  "payment_method_types": ["us_bank_account"],
  "payment_method_data": {
    "type": "us_bank_account",
    "us_bank_account": {
      "routing_number": "12341234",
      "account_number": "0123456789",
      "account_holder_type": "individual" | "company"
    },
    "billing_details": {
      // `name` must be specified for `us_bank_account` type
      "name": "Jenny Rosen",
      "phone": null | "{{String}}",
      "email": null | "{{String}}",
      "address": null | {
        "line1": null | "{{String}}",
        "line2": null | "{{String}}",
        "city": null | "{{String}}",
        "state": null | "{{String}}",
        "postal_code": null | "{{String}}",
        "country": null | "{{String}}"
      }
    }
  },
  // For `inbound` flows, we need to verify the bank account
  "payment_method_options": {
    "us_bank_account": {
      "verification_method": "microdeposits"
    }
  },
  // For `inbound` flows with us_bank_account, we need mandate information
  "mandate_data": {
    "customer_acceptance": {
      "type": "online",
      "online": {
        "ip_address": "123.123.123.123",
        "user_agent": "curl/1.2.3"
      }
    }
  },
  "confirm": true
}
```

`SetupIntent` は、以下のいずれかのステータスになります。

| ステータス             | 説明                            | 次のステップ                                |
| ----------------- | ----------------------------- | ------------------------------------- |
| `succeeded`       | 銀行口座が即座に確認されたか、確認が不要でした。      | アクションは不要です。                           |
| `requires_action` | 銀行口座の確認を完了するには、追加のアクションが必要です。 | 詳細な設定ステップについては、`next_action` をご覧ください。 |

`SetupIntent` の確認に成功すると、Stripe は同意書と徴収した銀行アカウントの詳細を確認するメールを連結アカウントに送信します。デフォルトのメールは Stripe Payments を参照しているため、Stripe Payments のないプラットフォームで金融口座を使用する場合は、Stripe のメールをオフにし、代わりに [カスタムメッセージ](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails) を送信することをお勧めします。