# カナダでの将来のプレオーソリデビットによる支払いに備えて支払い方法の詳細を保存する

将来のカナダのプレオーソリデビット支払いに備えて支払い方法の詳細を保存します。

# Checkout

> This is a Checkout for when payment-ui is checkout. View the full page at https://docs.stripe.com/payments/acss-debit/set-up-payment?payment-ui=checkout.

[Setup Intents API](https://docs.stripe.com/payments/setup-intents.md) を使用して、事前に支払い方法の詳細を収集し、後から最終的な金額や支払い日を確定できます。この機能が役立つ用途を紹介します。

- 支払い方法をウォレットに保存して、以降の購入を効率化する
- サービスの提供後に追加料金を回収する
- サブスクリプションの無料トライアルを開始する

> Pre-authorized debit in Canada は **通知遅延型の決済手段** であるため、決済後すぐには売上が利用可能になりません。通常、アカウントへの入金までに **5 business days** かかります。

カナダのほとんどの銀行口座で保有されているのはカナダドル (CAD) ですが、少数ながらアメリカドル (USD) などの他の通貨を保有する口座もあります。PAD では CAD と USD のどちらでの決済も可能ですが、決済の失敗を避けるため、顧客に適切な通貨を選択することが重要です。

多くのカードベースの支払い方法とは異なり、CAD の口座からの USD での引き落としや、USD の口座からの CAD での引き落としは成功しない可能性があります。多くの場合、このような引き落としを試行すると、遅延して支払い失敗が発生します。この遅延は最大 5 営業日です。

このような決済エラーを避けるには、顧客のアカウントが確実に USD での引き落としに対応している場合を除き、PAD の銀行口座は CAD に設定するのが最も安全です。

## Stripe を設定する [サーバ側]

まず、Stripe アカウントが必要です。[今すぐ登録](https://dashboard.stripe.com/register)してください。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

#### 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 オブジェクトの ID を、独自の内部的な顧客の表記に関連付けることにより、保存された決済手段の詳細を後で取得して使用できます。顧客がアカウントを作成していない場合でも、すぐに Customer オブジェクトを作成し、後でこのオブジェクトを顧客のアカウントの内部表記に関連付けることができます。

新しい Customer を作成するか、または既存の Customer を取得して、この支払い詳細に関連付けます。サーバに以下のコードを含め、新しい Customer を作成します。

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

## 支払いを事前設定する

> このガイドは、[支払いを事前設定する](https://docs.stripe.com/payments/save-and-reuse.md) Checkout の基本的な実装が存在することを前提としています。

このガイドでは、カナダの事前承認デビット (PAD) を有効化する手順を解説します。動的な決済方法を使用して支払いを受け付ける方法と、決済方法を手動で設定する方法、そして PAD を使用した場合との違いを明らかにしています。

### 支払い方法としてカナダのプレオーソリデビットを有効にする

新しい [Checkout Session (セッション)](https://docs.stripe.com/api/checkout/sessions.md) を作成する際は、以下を行う必要があります。

1. `acss_debit` を `payment_method_types` のリストに追加します。
1. 追加の [payment_method_options](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_options-acss_debit) パラメーターを指定して、取引を説明します。詳細は以下をご覧ください。

Payments では、顧客が決済時に承認する [Payment Schedule (支払いスケジュール)](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-acss_debit-mandate_options-payment_schedule) を指定する必要があります。ビジネスに適した同意書オプションの選択方法については、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)を参照してください。

| パラメータ                                                                       | 値                                                                                                                                                               | 必要                                                      |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `payment_method_options[acss_debit][currency]`                              | この支払い方法で将来の支払いに使用する通貨。顧客の銀行口座の通貨と一致する必要があります。使用可能な値は `cad` または `usd` です。                                                                                        | はい                                                      |
| `payment_method_options[acss_debit][mandate_options][payment_schedule]`     | 同意書の支払いスケジュール。使用可能な値は `interval`、`sporadic`、`combined` です。ビジネスに適したスケジュールを選択するには、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)の概要を参照してください。 | はい                                                      |
| `payment_method_options[acss_debit][mandate_options][interval_description]` | 支払いスケジュールについて説明するテキスト。ビジネスに適した間隔の説明を作成するには、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)の概要を参照してください。                                      | `payment_schedule` の値が `interval` または `combined` の場合は必須 |
| `payment_method_options[acss_debit][mandate_options][transaction_type]`     | 同意書を使用する取引のタイプ。`personal` 的な理由による取引の場合と `business` 的な理由による取引の場合があります。                                                                                           | はい                                                      |
| `payment_method_options[acss_debit][mandate_options][default_for]`          | 同意書の目的列。詳細については、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)の概要を参照して、ビジネスに適したデフォルトの目的を選択してください。                                           | いいえ                                                     |

### Checkout セッションを作成する

#### Stripe がオンラインで提供するページ

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d mode=setup \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \
  -d "payment_method_types[]=acss_debit" \
  --data-urlencode "success_url=https://example.com/success"
```

#### 組み込みフォーム

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d mode=setup \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \
  -d "payment_method_types[]=acss_debit" \
  --data-urlencode "return_url=https://example.com/return" \
  -d ui_mode=embedded_page
```

Checkout セッション中に、銀行口座の詳細の収集と即時の確認を処理する UI モーダルが顧客に表示されます。オプションで少額入金を使用した確認へのフォールバックも可能です。顧客が少額入金による確認を選択した場合、Stripe は指定された銀行口座に 2 回の少額入金を自動的に送金します。この少額入金は、顧客のオンライン銀行明細書に表示されるまでに 1 〜 2 営業日かかります。入金が到着する予定になると、金額を*確定* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects)し、Stripe で銀行口座を確認するためのリンクが記載されたメールが顧客に届きます。確認が完了すると、その決済手段は、今後の決済に使用できるようになります。

## 組み込みをテストする

### テスト用の決済手段トークン

テスト用の決済手段トークンを使用すると、銀行口座の詳細を手動で入力することなく、連携をテストできます。これらのトークンを使用すると、銀行口座情報の収集と確認のステップが省略できます。

| トークン                              | シナリオ                          |
| --------------------------------- | ----------------------------- |
| `pm_acssDebit_success`            | 同意書が承認されると、直ちに決済できます。         |
| `pm_acssDebit_noAccount`          | 口座が見つからないため、支払いは失敗します。        |
| `pm_acssDebit_accountClosed`      | 口座が解約済みであるため、支払いは失敗します。       |
| `pm_acssDebit_insufficientFunds`  | 残高不足のため、支払いは失敗します。            |
| `pm_acssDebit_debitNotAuthorized` | 引き落としがオーソリされていないため、支払いは失敗します。 |
| `pm_acssDebit_dispute`            | 決済は成功しますが、不審請求の申し立てが発生します。    |

### テスト用の口座番号

Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号をいくつか用意しています。支払いが自動的に成功または失敗するすべてのテスト用の口座は、以下のテスト用の少額入金を使用して確認してから設定を完了する必要があります。

| 銀行番号  | 支店番号    | 口座番号           | シナリオ                                       |
| ----- | ------- | -------------- | ------------------------------------------ |
| `000` | `11000` | `000123456789` | 少額入金が確認された後、支払いが直ちに成功します。                  |
| `000` | `11000` | `900123456789` | 少額入金が確認された後、3 分遅延してから支払いが成功します。            |
| `000` | `11000` | `000222222227` | 少額入金が確認された後、支払いが直ちに失敗します。                  |
| `000` | `11000` | `900222222227` | 少額入金が確認された後、3 分遅延してから支払いが失敗します。            |
| `000` | `11000` | `000666666661` | 確認用の少額入金の送金が失敗します。                         |
| `000` | `11000` | `000777777771` | 支払い金額が原因でアカウントの週次支払い金額の上限を超えるため、支払いが失敗します。 |
| `000` | `11000` | `000888888881` | 支払い金額がアカウントの取引限度額を超えているため、支払いが失敗します。       |

サンドボックスで銀行口座確認の成功または失敗を再現するには、少額入金に以下の特定の金額を使用してください。

| 少額入金の金額         | シナリオ                      |
| --------------- | ------------------------- |
| `32` および `45`   | 口座が無事に確認されます。             |
| `10` および `11`   | 許容された確認回数の超過をシミュレーションします。 |
| その他の任意の数字の組み合わせ | 口座の確認が失敗します。              |

## 支払い方法を使用する [サーバ側]

Checkout セッションが完了すると、[PaymentMethod](https://docs.stripe.com/api/payment_methods.md) ID と [Mandate](https://docs.stripe.com/api/mandates.md) ID を[収集](https://docs.stripe.com/payments/checkout/save-and-reuse.md?payment-ui=stripe-hosted#retrieve-checkout-session)できます。これらを使用して、顧客に銀行口座の入力を再度求めることなく将来の決済を開始できます。

> 今後のプレオーソリの引き落としによる決済は、既存の同意書の条件に従って請求する必要があります。同意書の条件を満たさないタイミングでの引き落としは、支払いに関する不審請求の申請の原因となる可能性があります。

オフセッションで顧客に請求する準備ができたら、[PaymentIntent の作成](https://docs.stripe.com/api/payment_intents/create.md)時に `payment_method`、`customer`、`mandate` ID を指定します。

SetupIntent ID を取得していない場合は、顧客に関連付けられた SetupIntents に対して[リスト表示](https://docs.stripe.com/api/setup_intents/list.md)を実行することで、請求する PaymentMethod と同意書を調べることができます。以下が可能です。

```curl
curl -G https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}"
```

### 既存の承認済み同意書を使用して決済手段を再利用する

適切な SetupIntent の PaymentMethod ID と同意書 ID が存在する場合は、決済の金額と通貨を指定して PaymentIntent を作成します。その他のいくつかのパラメーターを設定して、*オフセッションの決済* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)を作成します。

- PaymentIntent の [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) プロパティの値を `true` に設定します。これにより、PaymentIntent が作成されると直ちに確定されます。
- [payment_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method) を PaymentMethod の ID に、[mandate](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-mandate) を Mandate の ID に、[customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) を Customer の ID にそれぞれ設定します。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=acss_debit" \
  -d "payment_method={{PAYMENTMETHOD_ID}}" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "mandate={{MANDATE_ID}}" \
  -d confirm=true \
  -d amount=100 \
  -d currency=cad
```

既存の同意書を新しい PaymentIntent で再利用する際には、その時点で引き落とし通知メールを送信する必要があります。[カスタム通知の送信](https://docs.stripe.com/payments/acss-debit.md#mandate-and-debit-notification-emails)を選択しない限り、Stripe がデフォルトでこの処理を行います。

## Optional: 即時の確認のみ [サーバ側]

デフォルトでは、カナダのプレオーソリデビットの決済で、顧客は銀行口座の即時確認、または少額入金を使用できます。オプションで、Checkout セッションの作成時に `payment_method_options[acss_debit][verification_method]`パラメーターを使用するだけで、銀行口座の即時確認のみを要求することもできます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=setup \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_types[]=acss_debit" \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  --data-urlencode "payment_method_options[acss_debit][mandate_options][interval_description]=On November 25, 2021" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \
  -d "payment_method_options[acss_debit][verification_method]=instant" \
  --data-urlencode "success_url=https://example.com/success"
```

## Optional: 少額入金による確認のみ [サーバ側]

デフォルトでは、カナダのプレオーソリデビット決済では、顧客は銀行口座の即時確認、または少額入金を使用できます。オプションで、Checkout セッションの作成時に `payment_method_options[acss_debit][verification_method]` パラメーターを使用するだけで、銀行口座の即時確認のみを要求することもできます。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=setup \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_types[]=acss_debit" \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  --data-urlencode "payment_method_options[acss_debit][mandate_options][interval_description]=On November 25, 2021" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \
  -d "payment_method_options[acss_debit][verification_method]=microdeposits" \
  --data-urlencode "success_url=https://example.com/success"
```


# ダイレクト API

> This is a ダイレクト API for when payment-ui is direct-api. View the full page at https://docs.stripe.com/payments/acss-debit/set-up-payment?payment-ui=direct-api.

[Setup Intents API](https://docs.stripe.com/payments/setup-intents.md) を使用して、事前に支払い方法の詳細を収集し、後から最終的な金額や支払い日を確定できます。この機能が役立つ用途を紹介します。

- 支払い方法をウォレットに保存して、以降の購入を効率化する
- サービスの提供後に追加料金を回収する
- *サブスクリプション* (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)の無料トライアルを開始する

カナダのほとんどの銀行口座で保有されているのはカナダドル (CAD) ですが、少数ながらアメリカドル (USD) などの他の通貨を保有する口座もあります。PAD では CAD と USD のどちらでの決済も可能ですが、決済の失敗を避けるため、顧客に適切な通貨を選択することが重要です。

多くのカードベースの支払い方法とは異なり、CAD の口座からの USD での引き落としや、USD の口座からの CAD での引き落としは成功しない可能性があります。多くの場合、このような引き落としを試行すると、遅延して支払い失敗が発生します。この遅延は最大 5 営業日です。

このような決済エラーを避けるには、顧客のアカウントが確実に USD での引き落としに対応している場合を除き、PAD の銀行口座は CAD に設定するのが最も安全です。

## Stripe を設定する [サーバ側]

まず、Stripe アカウントが必要です。[今すぐ登録](https://dashboard.stripe.com/register)してください。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

#### 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* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) に関連付ける必要があります。

顧客がお客様のビジネスでアカウントを作成するときに、Customer オブジェクトを作成する必要があります。Customer オブジェクトの ID を、独自の顧客の内部表記に関連付けることにより、保存された支払い方法の詳細を後から取得して使用できます。顧客がアカウントを作成していない場合でも、すぐに Customer オブジェクトを作成し、後でこのオブジェクトを顧客のアカウントの内部表記に関連付けることができます。

新しい Customer を作成するか、または既存の Customer を取得して、この支払い詳細に関連付けます。サーバに以下のコードを含め、新しい Customer を作成します。

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

## SetupIntent を作成する [サーバ側]

[SetupIntent (支払い方法設定インテント)](https://docs.stripe.com/api/setup_intents.md) は、今後の決済に備えて顧客の支払い方法を設定する意図を表すオブジェクトです。`SetupIntent` は、この設定プロセスのステップを追跡します。

カナダのプリオーソリデビットを利用するには、プレオーソリデビット利用規約を通じて、1 回限りの引き落としと継続的な引き落としについて顧客から承認を得る必要があります ([PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)を参照)。[Mandate (同意書)](https://docs.stripe.com/api/mandates.md) オブジェクトは、この利用契約と承認を記録します。

[payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) を `acss_debit` に設定してサーバーで SetupIntent を作成し、Customer の [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) を指定します。この SetupIntent の [Mandate (同意書)](https://docs.stripe.com/api/mandates.md) に支払いスケジュールを定義するには、以下のパラメーターも含めてください。

| パラメータ                                                                       | 値                                                                                                                                                               | 必要                                                   |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `payment_method_options[acss_debit][currency]`                              | この支払い方法で将来の支払いに使用する通貨。顧客の銀行口座の通貨と一致する必要があります。使用可能な値は `cad` または `usd` です。                                                                                        | はい                                                   |
| `payment_method_options[acss_debit][mandate_options][payment_schedule]`     | 同意書の支払いスケジュール。使用可能な値は `interval`、`sporadic`、`combined` です。ビジネスに適したスケジュールを選択するには、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)の概要を参照してください。 | はい                                                   |
| `payment_method_options[acss_debit][mandate_options][interval_description]` | 支払いスケジュールの間隔について説明するテキスト。ビジネスに適した間隔の説明を作成するには、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)の概要を参照してください。                                   | `payment_schedule` の値が `interval` または `combined` の場合 |
| `payment_method_options[acss_debit][mandate_options][transaction_type]`     | 同意書を使用する取引のタイプ。`personal` 的な理由による取引の場合と `business` 的な理由による取引の場合があります。                                                                                           | はい                                                   |
| `payment_method_options[acss_debit][mandate_options][default_for]`          | 同意書の目的列。詳細については、[PAD 同意書](https://docs.stripe.com/payments/acss-debit.md#mandates)の概要を参照して、ビジネスに適したデフォルトの目的を選択してください。                                           | いいえ                                                  |

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=acss_debit" \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal"
```

### client secret を取得する

SetupIntent には、*client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。

#### 1 ページのアプリケーション

ブラウザーの `fetch` 関数を使用して、サーバーのエンドポイントから client secret を取得します。この方法は、クライアント側が 1 ページのアプリケーションで、特に React などの最新のフロントエンドフレームワークで構築されている場合に最適です。client secret を処理するサーバーのエンドポイントを作成します。

#### Ruby

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

その後、クライアント側で JavaScript を使用して client secret を取得します。

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

#### サーバ側のレンダリング

サーバーからクライアントに client secret を渡します。この方法は、アプリケーションがブラウザーへの送信前に静的なコンテンツをサーバーで生成する場合に最適です。

決済フォームに [client_secret](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) を追加します。サーバー側のコードで、SetupIntent から client secret を取得します。

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

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

## 支払い方法の詳細と同意書承認を収集する [クライアント側]

顧客が Canadian pre-authorized debitでの支払いをクリックしたときに、Stripe.js を使用してその支払いを Stripe に送信することをお勧めします。[Stripe.js](https://docs.stripe.com/payments/elements.md) は、決済フローを構築するための Stripe の基本的な JavaScript ライブラリです。これにより、実装に関する複雑な処理が自動的に行われ、将来、他の決済手段にも対応できるように実装を簡単に拡張できます。

Stripe.js スクリプトを決済ページに含めるには、このスクリプトを HTML ファイルの `head` に追加します。

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

決済ページで以下の JavaScript を使用して、Stripe.js のインスタンスを作成します。

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

PaymentIntent オブジェクト全体をクライアントに送信する代わりに、前のステップからの *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) を使用します。これは、Stripe API リクエストを認証する API キーとは異なります。

それでも、client secret は支払いを完了できるため、慎重に扱う必要があります。記録したり、URL に埋め込んだり、その顧客以外に公開されることがないようにしてください。

ユーザーがフォームを送信したら、[stripe.confirmAcssDebitSetup](https://docs.stripe.com/js/setup_intents/confirm_acss_debit_setup) を使用して、銀行口座の詳細と確認を収集し、同意書を確認し、設定を完了します。PAD の決済手段を作成するには、`payment_method` パラメーターの `billing_details` プロパティに顧客のメールアドレスと口座名義人を含める必要があります。

```javascript
const form = document.getElementById('payment-form');
const accountholderName = document.getElementById('accountholder-name');
const email = document.getElementById('email');
const submitButton = document.getElementById('submit-button');
const clientSecret = submitButton.dataset.secret;

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

  const {setupIntent, error} = await stripe.confirmAcssDebitSetup(
    clientSecret,
    {
      payment_method: {
        billing_details: {
          name: accountholderName.value,
          email: email.value,
        },
      },
    }
  );

  if (error) {
    // Inform the customer that there was an error.
    console.log(error.message);
  } else {
      // Handle next step based on SetupIntent's status.
      console.log("SetupIntent ID: " + setupIntent.id);
      console.log("SetupIntent status: " + setupIntent.status);
  }
});
```

Stripe.js は、ページ上のモーダル UI をロードして、銀行口座の詳細の収集と銀行口座の確認を処理し、オンライン同意書を提示して承認を収集します。

> `stripe.confirmAcssDebitSetup` の完了には数秒かかる場合があります。この間、フォームが再送信されないように無効化し、スピナーのような待機中のインジケーターを表示します。エラーが発生した場合は、それを顧客に表示し、フォームを再度有効化し、待機中のインジケーターを非表示にします。

成功した場合、Stripe は [SetupIntent (支払い方法設定インテント)](https://docs.stripe.com/api/setup_intents/object.md) オブジェクトを、以下のステータスのいずれかで返します。

| ステータス             | 説明                            | 次のステップ                                                                                                                |
| ----------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `succeeded`       | 銀行口座が即座に確認されたか、確認が必要ありませんでした。 | アクションは不要です                                                                                                            |
| `requires_action` | 銀行口座の確認を完了するには、追加のアクションが必要です。 | ステップ 5: [少額入金で銀行口座を確認する](https://docs.stripe.com/payments/acss-debit/set-up-payment.md#web-verify-with-microdeposits) |

SetupIntent の確認に成功した後、同意書の確認メールと収集した銀行口座の詳細を顧客に送信する必要があります。Stripe はデフォルトでこれらの処理を行いますが、ご希望に応じて[カスタム通知の送信](https://docs.stripe.com/payments/acss-debit.md#mandate-and-debit-notification-emails)を選択することができます。

> 組み込みをテストする際、同意書の確認メールは顧客のメールアドレスに送信されません。

顧客が確認フローを完了せずにモーダルを閉じることを選択した場合、Stripe.js は次のようなエラーを返します。

```json
{
  "error": {
    "type": "validation_error",
    "code": "incomplete_payment_details",
    "message": "Please provide complete payment details."
  }
}
```

## 少額入金で銀行口座を確認する [クライアント側]

すべての顧客が銀行口座を即座に確認できるとは限りません。このステップは、顧客が前のステップで即時確認フローからオプトアウトした場合にのみ適用されます。

この場合、Stripe は顧客の銀行口座に 2 回に分けて少額入金を自動的に行います。これらの入金が顧客のオンライン明細書に表示され、`ACCTVERIFY` 明細書表記が付けられるまでに 1〜2 営業日かかります。

`stripe.confirmAcssDebitSetup` メソッドの呼び出しの結果として、`requires_action` 状態の SetupIntent が返されます。SetupIntent には、確認を完了するための有益な情報を含む `next_action` フィールドが含まれています。

Stripe は[請求書メール](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-billing_details-email)で入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了することができます。

確認の失敗は 3 回までです。この上限を超えると、銀行口座の確認ができなくなります。また、少額入金の確認は 10 日経過するとタイムアウトになります。少額入金がこの期間内に確認されない場合、PaymentIntent は新しい決済手段の詳細を要求する状態に戻ります。少額入金とは何か、どのように使用するのかを顧客に明確に伝えることで、顧客は確認に関連する問題を回避できます。

### オプション: カスタムのメールと確認ページ

[カスタムのメール通知](https://docs.stripe.com/payments/acss-debit.md#mandate-and-debit-notification-emails)の送信を選択した場合は、顧客にメールを送信する必要があります。このためには、`next_action` オブジェクトの `verify_with_microdeposits[hosted_verification_url]` の URL を使用して、顧客に確認プロセスを完了するよう指示します。

カスタムメールを送信していて、Stripe がオンラインで提供する確認ページを使用しない場合、[Stripe.js](https://docs.stripe.com/js/payment_intents/verify_microdeposits_for_payment) を使用して、顧客がこれらの金額をお客様に伝えて銀行口座を確認するためのフォームを自社サイトに作成できます。

```javascript
stripe.verifyMicrodepositsForSetup(clientSecret, {
  amounts: [32, 45],
});
```

銀行口座の確認に成功すると、Stripe は `succeeded` の `status` で [SetupIntent (支払い方法設定インテント) オブジェクト](https://docs.stripe.com/api/setup_intents/object.md)を返し、`setup_intent.succeeded` Webhook イベントを送信します。

確認が失敗する原因はいくつか存在します。失敗は直接的なエラー応答で同期的に発生することも、`setup_intent.payment_failed` Webhook イベントを通じて非同期で発生することもあります (以下の例を参照してください)。

#### 同期エラー

```json
{
  "error": {
    "code": "payment_method_microdeposit_verification_amounts_mismatch",
    "message": "The amounts provided do not match the amounts that were sent to the bank account. You have {attempts_remaining} verification attempts remaining.",
    "type": "invalid_request_error"
  }
}
```

#### Webhook イベント

```javascript
{
  "object": {
    "id": "seti_1234",
    "object": "setup_intent",
    "customer": "cus_0246",
    ...
    "last_setup_error": {
      "code": "payment_method_microdeposit_verification_attempts_exceeded",
      "message": "You have exceeded the number of allowed verification attempts."
    },
    ...
    "status": "requires_payment_method"
  }
}
```

| エラーコード                                                       | 同期または非同期                      | メッセージ                                                              | ステータスの変更                                                           |
| ------------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `payment_method_microdeposit_failed`                         | 同期、または Webhook イベントを通じて非同期で発生 | 少額入金に失敗しました。指定した銀行口座、金融機関、支店の番号を確認してください                           | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 |
| `payment_method_microdeposit_verification_amounts_mismatch`  | 同期                            | 指定された金額が銀行口座に送金された金額と一致しません。確認試行の残り回数はあと {attempts_remaining} 回です。 | 変化なし                                                               |
| `payment_method_microdeposit_verification_attempts_exceeded` | 同期、および Webhook イベントを通じて非同期で発生 | 許容された確認の試行回数を超えました                                                 | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 |
| `payment_method_microdeposit_verification_timeout`           | Webhook イベントを通じて非同期で発生        | 少額入金がタイムアウトになりました。顧客は要求された 10 日の期間内に銀行口座を確認しませんでした。                | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 |

## 組み込みをテストする

### テスト用の決済手段トークン

テスト用の決済手段トークンを使用すると、銀行口座の詳細を手動で入力することなく、連携をテストできます。これらのトークンを使用すると、銀行口座情報の収集と確認のステップが省略できます。

| トークン                              | シナリオ                          |
| --------------------------------- | ----------------------------- |
| `pm_acssDebit_success`            | 同意書が承認されると、直ちに決済できます。         |
| `pm_acssDebit_noAccount`          | 口座が見つからないため、支払いは失敗します。        |
| `pm_acssDebit_accountClosed`      | 口座が解約済みであるため、支払いは失敗します。       |
| `pm_acssDebit_insufficientFunds`  | 残高不足のため、支払いは失敗します。            |
| `pm_acssDebit_debitNotAuthorized` | 引き落としがオーソリされていないため、支払いは失敗します。 |
| `pm_acssDebit_dispute`            | 決済は成功しますが、不審請求の申し立てが発生します。    |

### テスト用の口座番号

Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号をいくつか用意しています。支払いが自動的に成功または失敗するすべてのテスト用の口座は、以下のテスト用の少額入金を使用して確認してから設定を完了する必要があります。

| 銀行番号  | 支店番号    | 口座番号           | シナリオ                                       |
| ----- | ------- | -------------- | ------------------------------------------ |
| `000` | `11000` | `000123456789` | 少額入金が確認された後、支払いが直ちに成功します。                  |
| `000` | `11000` | `900123456789` | 少額入金が確認された後、3 分遅延してから支払いが成功します。            |
| `000` | `11000` | `000222222227` | 少額入金が確認された後、支払いが直ちに失敗します。                  |
| `000` | `11000` | `900222222227` | 少額入金が確認された後、3 分遅延してから支払いが失敗します。            |
| `000` | `11000` | `000666666661` | 確認用の少額入金の送金が失敗します。                         |
| `000` | `11000` | `000777777771` | 支払い金額が原因でアカウントの週次支払い金額の上限を超えるため、支払いが失敗します。 |
| `000` | `11000` | `000888888881` | 支払い金額がアカウントの取引限度額を超えているため、支払いが失敗します。       |

サンドボックスで銀行口座確認の成功または失敗を再現するには、少額入金に以下の特定の金額を使用してください。

| 少額入金の金額         | シナリオ                      |
| --------------- | ------------------------- |
| `32` および `45`   | 口座が無事に確認されます。             |
| `10` および `11`   | 許容された確認回数の超過をシミュレーションします。 |
| その他の任意の数字の組み合わせ | 口座の確認が失敗します。              |

## Optional: 将来の決済を受け付ける [サーバ側]

SetupIntent が完了すると、新しい *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) オブジェクトと[同意書](https://docs.stripe.com/api/mandates.md)オブジェクトができます。オブジェクトを使用して、顧客に銀行口座の再入力を求めることなく、将来の決済を開始できます。

> 将来のプレオーソリデビット決済は、既存の同意書の規約に従って請求する必要があります。同意書の規約を満たさない随時の引き落としは、決済の不審請求の申し立てを引き起こす可能性があります。

オフセッションで顧客に決済する準備ができたら、Customer、PaymentMethod、同意書の各 ID を使用して、PaymentIntent を作成します。

SetupIntent ID を取得していない場合は、顧客に関連付けられた SetupIntents に対して[リスト表示](https://docs.stripe.com/api/setup_intents/list.md)を実行することで、請求する PaymentMethod と同意書を調べることができます。以下が可能です。

```curl
curl -G https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}"
```

### 既存の承認済み同意書を使用して決済手段を再利用する

適切な SetupIntent の PaymentMethod ID と同意書 ID が存在する場合は、決済の金額と通貨を指定して PaymentIntent を作成します。その他のいくつかのパラメーターを設定して、*オフセッションの決済* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)を作成します。

- PaymentIntent の [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) プロパティの値を `true` に設定します。これにより、PaymentIntent が作成されると直ちに確定されます。
- [payment_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method) を PaymentMethod の ID に、[mandate](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-mandate) を Mandate の ID に、[customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) を Customer の ID にそれぞれ設定します。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=acss_debit" \
  -d "payment_method={{PAYMENTMETHOD_ID}}" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "mandate={{MANDATE_ID}}" \
  -d confirm=true \
  -d amount=100 \
  -d currency=cad
```

既存の同意書を新しい PaymentIntent で再利用する際には、その時点で引き落とし通知メールを送信する必要があります。[カスタム通知の送信](https://docs.stripe.com/payments/acss-debit.md#mandate-and-debit-notification-emails)を選択しない限り、Stripe がデフォルトでこの処理を行います。

### 新しい同意書で決済手段を再利用する

異なる条件で顧客から引き落としを行う必要があるが、銀行口座情報の再入力を要求したくない場合も、既存の PaymentMethod を再利用して、新しい同意書に対して顧客の承認を得ることができます。これを行うには、[新しい PaymentIntent を作成する](https://docs.stripe.com/payments/acss-debit/accept-a-payment.md#web-create-payment-intent)または[新しい SetupIntent を作成する](https://docs.stripe.com/payments/acss-debit/set-up-payment.md#web-create-setup-intent)の説明に従って、以下の変更を行います。

- 新しい PaymentIntent または SetupIntent の作成時に、既存の PaymentMethod の ID を値として指定し、`payment_method` パラメータを追加します。
- `stripe.confirmAcssDebitPayment` または `stripe.confirmAcssDebitSetup` を呼び出す際に、支払い方法の詳細を送信するステップで `payment_method` と `acss_debit` の各データを省略します。

> 再利用された PaymentMethod と新しい Mandate で作成された PaymentIntents および SetupIntents に対する確認は必要ありませんが、新しい同意書の確認電子メールを送信する必要があり、決済に 3 日間の遅延が発生します。

## Optional: 即時の確認のみ [サーバ側]

デフォルトでは、カナダのプレオーソリデビットの決済で、顧客は銀行口座の即時確認、または少額入金を使用できます。オプションで、PaymentIntent の作成時に [verification_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-acss_debit-verification_method)パラメーターを使用するだけで、銀行口座の即時確認のみを要求することもできます。

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=acss_debit" \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \
  -d "payment_method_options[acss_debit][verification_method]=instant"
```

## Optional: 少額入金による確認のみ [サーバ側]

デフォルトでは、カナダのプレオーソリデビット決済では、顧客は銀行口座の即時確認、または少額入金を使用できます。オプションで、PaymentIntent の作成時に [verification_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-acss_debit-verification_method) パラメーターを使用するだけで、銀行口座の即時確認のみを要求することもできます。

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=acss_debit" \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_options[acss_debit][currency]=cad" \
  -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \
  -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \
  -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \
  -d "payment_method_options[acss_debit][verification_method]=microdeposits"
```

## See also

- [カナダのプリオーソリデビットによる支払いを受け付ける](https://docs.stripe.com/payments/acss-debit/accept-a-payment.md)