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

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

Setup Intents API を使用して、事前に支払い方法の詳細を収集し、後から最終的な金額や支払い日を確定できます。この機能が役立つ用途を紹介します。

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

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

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

このような支払い失敗を避けるには、顧客の口座が間違いなく USD での引き落としに対応している場合を除き、PAD の銀行口座の引き落としは CAD に設定するのが最も安全です。

Stripe を設定する
サーバ側

まず、Stripe アカウントが必要です。今すぐ登録してください。

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

Customer を作成または取得する
サーバ側

以降の支払いに銀行口座を再利用するには、その口座を Customer に関連付ける必要があります。

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

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

SetupIntent を作成する
サーバ側

SetupIntent (支払い方法設定インテント) は、今後の決済に備えて顧客の支払い方法を設定する意図を表すオブジェクトです。SetupIntent は、この設定プロセスのステップを追跡します。

To use Canadian pre-authorized debits, you must obtain authorization from your customer for one-time and recurring debits using a pre-authorized debit agreement (see PAD Mandates). The Mandate object records this agreement and authorization.

Create a SetupIntent on your server with payment_method_types set to acss_debit and specify the Customer’s id. To define a payment schedule on the Mandate for this SetupIntent, also include the following parameters:

パラメータ	値	必須か否か
`payment_method_options[acss_debit][currency]`	この支払い方法で将来の支払いに使用する通貨。顧客の銀行口座の通貨と一致する必要があります。使用可能な値は `cad` または `usd` です。	はい
`payment_method_options[acss_debit][mandate_options][payment_schedule]`	同意書の支払いスケジュール。使用可能な値は `interval`、`sporadic`、`combined` です。ビジネスに適したスケジュールを選択するには、PAD 同意書の概要を参照してください。	はい
`payment_method_options[acss_debit][mandate_options][interval_description]`	支払いスケジュールの間隔について説明するテキスト。ビジネスに適した間隔の説明を作成するには、PAD 同意書の概要を参照してください。	`payment_schedule` の値が `interval` または `combined` の場合
`payment_method_options[acss_debit][mandate_options][transaction_type]`	作成する同意書のタイプ。`personal` (顧客が個人の場合) または `business` (顧客がビジネスの場合) のいずれかです。	はい

client secret を取得する

SetupIntent には、client secret が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。

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

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

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

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

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

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

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

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

client.js
// 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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

PaymentIntent オブジェクト全体をクライアントに送信する代わりに、前のステップからの client secret を使用します。これは、Stripe API リクエストを認証する API キーとは異なります。

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

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

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 (支払い方法設定インテント) オブジェクトを、以下のステータスのいずれかで返します。

ステータス	説明	次のステップ
`succeeded`	銀行口座が即座に確認されたか、確認が必要ありませんでした。	アクションは不要です
`requires_action`	銀行口座の確認を完了するには、追加のアクションが必要です。	ステップ 5: 少額入金で銀行口座を確認する

SetupIntent の確認に成功した後、同意書の確認メールと収集した銀行口座の詳細を顧客に送信する必要があります。Stripe はデフォルトでこれらの処理を行いますが、ご希望に応じてカスタム通知の送信を選択することができます。

注

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

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

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

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

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

In this case, Stripe automatically sends two micro-deposits to the customer’s bank account. These deposits take 1–2 business days to appear on the customer’s online statement and have statement descriptors that include ACCTVERIFY.

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

Stripe は請求書メールで入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了することができます。

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

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

カスタムのメール通知の送信を選択した場合は、顧客にメールを送信する必要があります。このためには、next_action オブジェクトの verify_with_microdeposits[hosted_verification_url] の URL を使用して、顧客に確認プロセスを完了するよう指示します。

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

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

銀行口座の確認に成功すると、Stripe は succeeded の status で SetupIntent (支払い方法設定インテント) オブジェクトを返し、setup_intent.succeeded Webhook イベントを送信します。

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

{
  "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"
  }
}

エラーコード	同期または非同期	メッセージ	ステータスの変更
`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` が設定されます。

組み込みをテストする

少額入金の確認メールを受信する

To receive the micro-deposit verification email in a sandbox after collecting the bank account details and accepting a mandate, provide an email in the payment_method[billing_details][email] field in the form of {any_prefix}+test_email@{any_domain} when confirming the payment method details.

テスト用の口座番号

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

銀行番号	支店番号	口座番号	シナリオ
`000`	`11000`	`000123456789`	少額入金が確認された後、支払いが直ちに成功します。
`000`	`11000`	`900123456789`	少額入金が確認された後、3 分遅延してから支払いが成功します。
`000`	`11000`	`000222222227`	少額入金が確認された後、支払いが直ちに失敗します。
`000`	`11000`	`900222222227`	少額入金が確認された後、3 分遅延してから支払いが失敗します。
`000`	`11000`	`000666666661`	確認用の少額入金の送金が失敗します。
`000`	`11000`	`000777777771`	Fails the payment due to the payment amount causing the account to exceed its weekly payment volume limit.
`000`	`11000`	`000888888881`	Fails the payment due to the payment amount exceeding the account’s transaction limit.

To mimic successful or failed bank account verifications in a sandbox, use these meaningful amounts for micro-deposits:

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

注

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

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

Stripe を設定する
サーバ側

Customer を作成または取得する
サーバ側

SetupIntent を作成する
サーバ側

client secret を取得する

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

注

注

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

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

組み込みをテストする

少額入金の確認メールを受信する

テスト用の口座番号

オプション将来の決済を受け付ける
サーバ側

オプション即時の確認のみ
サーバ側

オプション少額入金による確認のみ
サーバ側

参照情報

注

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

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

Stripe を設定するサーバ側

Customer を作成または取得するサーバ側

SetupIntent を作成するサーバ側

client secret を取得する

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

注

注

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

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

組み込みをテストする

少額入金の確認メールを受信する

テスト用の口座番号

オプション将来の決済を受け付けるサーバ側

オプション即時の確認のみサーバ側

オプション少額入金による確認のみサーバ側

参照情報

Stripe を設定する
サーバ側

Customer を作成または取得する
サーバ側

SetupIntent を作成する
サーバ側

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

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

オプション将来の決済を受け付ける
サーバ側

オプション即時の確認のみ
サーバ側

オプション少額入金による確認のみ
サーバ側