カナダのプレオーソリデビットの支払いを受け付ける
Web サイトでのカナダのプレオーソリデビット (PAD) 支払いの受け付けは、支払いを追跡するオブジェクトの作成、支払い方法に関する情報と同意書承認の収集、支払いを処理するための Stripe への支払いの送信、および顧客の銀行口座の確認で構成されます。
Stripe では、Payment Intent (支払いインテント) と呼ばれる支払いオブジェクトを使用して、支払いが完了するまでの状態のすべてを追跡および処理します。
Customer を作成または取得するサーバ側
以降の支払いに銀行口座を再利用するには、その口座を Customer に関連付ける必要があります。
顧客がお客様のビジネスでアカウントを作成する際、Customer オブジェクトを作成します。この Customer オブジェクトの ID を、顧客を表す独自の内部表記と関連付けることで、保存した支払い方法の詳細を後で取得して使用することができます。
新しい Customer を作成するか、または既存の Customer を取得して、この支払いに関連付けます。サーバに以下のコードを含め、新しい Customer を作成します。
PaymentIntent を作成するサーバ側
PaymentIntent (支払いインテント) は、顧客から支払いを回収する意図を表すオブジェクトで、支払いプロセスのライフサイクルの各段階を追跡します。
カナダのプレオーソリデビットを使用するには、プレオーソリデビット利用規約を使用して、1 回限りの引き落としと継続的な引き落としについて顧客から承認を得る必要があります (PAD 同意書 を参照)。Mandate (同意書) オブジェクトは、この利用契約と承認を記録します。
まず、サーバで PaymentIntent を作成し、回収する金額と通貨 (通常は cad
) を指定します。Payment Intents API を使用した組み込みがすでにある場合は、PaymentIntent の支払い方法のタイプの一覧に acss_debit
を追加します。Customer の ID を指定します。
その支払い方法を将来使用する場合には、値を off_session
に設定して setup_future_usage パラメーターを指定します。
この PaymentIntent の Mandate (同意書) で支払いスケジュールと確認方法を定義するには、以下のパラメータも含めます。
パラメータ | 値 | 必須か否か |
---|---|---|
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 を取得する
PaymentIntent には、client secret が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。
支払い方法の詳細を収集して送信するクライアント側
顧客が Canadian pre-authorized debitでの支払いをクリックしたときに、Stripe.js を使用してその支払いを Stripe に送信することをお勧めします。Stripe.js は、決済フローを構築するための Stripe の基本的な JavaScript ライブラリーです。これにより、組み込みに関する複雑な処理が自動的に行われ、将来、他の支払い方法にも対応できるように組み込みを簡単に拡張できます。
Stripe.js スクリプトを決済ページに含めるには、このスクリプトを HTML ファイルの head
に追加します。
<head> <title>Checkout</title> <script src="https://js.stripe.com/v3/"></script> </head>
決済ページで以下の JavaScript を使用して、Stripe.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.confirmAcssDebitPayment を使用して、銀行口座の詳細と銀行口座の確認を収集し、同意書を確認し、支払いを完了します。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 {paymentIntent, error} = await stripe.confirmAcssDebitPayment( 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 PaymentIntent's status. console.log("PaymentIntent ID: " + paymentIntent.id); console.log("PaymentIntent status: " + paymentIntent.status); } });
Stripe.js は、ページ上のモーダル UI をロードして、銀行口座の詳細の収集と銀行口座の確認を処理し、オンライン同意書を提示して承認を収集します。
注
stripe.confirmAcssDebitPayment
の完了には数秒かかる場合があります。この間、フォームが再送信されないように無効化し、スピナーのような待機中のインジケーターを表示します。エラーが発生した場合は、それを顧客に表示し、フォームを再度有効化し、待機中のインジケーターを非表示にします。
成功した場合、Stripe は PaymentIntent (支払いインテント) オブジェクトを、以下のステータスのいずれかで返します。
ステータス | 説明 | 次のステップ |
---|---|---|
processing | 銀行口座が即座に確認されたか、確認が必要ありませんでした。 | ステップ 6: PaymentIntent が成功したことを確認する |
requires_action | 銀行口座の確認を完了するには、追加のアクションが必要です。 | ステップ 5: 少額入金で銀行口座を確認する |
PaymentIntent の確認に成功した後、同意書の確認メールと収集した銀行口座の詳細を顧客に送信する必要があります。Stripe はデフォルトでこれらの処理を行いますが、ご希望に応じてカスタム通知の送信を選択することもできます。
注
組み込みのテストの際は、顧客のメールアドレスに同意書の確認は送信されません。
顧客が確認フローを完了せずにモーダルを閉じることを選択した場合、Stripe.js は次のようなエラーを返します。
{ "error": { "type": "validation_error", "code": "incomplete_payment_details", "message": "Please provide complete payment details." } }
少額入金で銀行口座を確認するクライアント側
すべての顧客が銀行口座を即座に確認できるとは限りません。このステップは、顧客が前のステップで即時確認フローからオプトアウトした場合にのみ適用されます。
この場合、Stripe は自動的に 2 件の少額入金を顧客の銀行口座に送金します。この入金は、1 ~ 2 営業日後に顧客のオンライン明細書に表示され、その明細書表記には、ACCTVERIFY
の表記が含まれます。
前のステップで行った stripe.confirmAcssDebitPayment
メソッドの呼び出しの結果として、requires_action
状態の PaymentIntent が返されます。この PaymentIntent には、確認を完了するための有益な情報を含む next_action
フィールドが含まれています。
Stripe は請求書メールで入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了することができます。
確認の失敗は 3 回までです。この上限を超えると、銀行口座の確認ができなくなります。また、少額入金の確認は 10 日経過するとタイムアウトになります。少額入金がこの期間内に確認されない場合、PaymentIntent は新しい支払い方法の詳細を要求する状態に戻ります。少額入金とは何か、どのように使用するのかを顧客に明確に伝えることで、顧客は確認に関連する問題を回避できます。
オプション: カスタムのメールと確認ページ
カスタムのメール通知の送信を選択した場合は、顧客にメールを送信する必要があります。このためには、next_action
オブジェクトの verify_with_microdeposits[hosted_verification_url]
の URL を使用して、顧客に確認プロセスを完了するよう指示します。
カスタムメールを送信していて、Stripe がオンラインで提供する確認ページを使用しない場合、Stripe.js を使用して、顧客がこれらの金額をお客様に伝えて銀行口座を確認するためのフォームを自社サイトに作成できます。
stripe.verifyMicrodepositsForPayment(clientSecret, { amounts: [32, 45], });
銀行口座の確認に成功すると、Stripe は PaymentIntent (支払いインテント) オブジェクトを processing
の status
で返し、payment_intent.processing
Webhook イベントを送信します。
確認が失敗する原因はいくつか存在します。失敗は直接的なエラー応答で同期的に発生することも、payment_intent.payment_failed
Webhook イベントを通じて非同期で発生することもあります (以下の例を参照してください)。
エラーコード | 同期または非同期 | メッセージ | ステータスの変更 |
---|---|---|---|
payment_method_microdeposit_failed | 同期、または Webhook イベントを通じて非同期で発生 | 少額入金に失敗しました。指定した銀行口座、金融機関、支店の番号を確認してください | status は requires_payment_method で、last_payment_error が設定されます。 |
payment_method_microdeposit_verification_amounts_mismatch | 同期 | 指定された金額が銀行口座に送金された金額と一致しません。確認試行の残り回数は {attempts_remaining} 回です。 | 変化なし |
payment_method_microdeposit_verification_attempts_exceeded | 同期、および Webhook イベントを通じて非同期で発生 | 許容された確認の試行回数を超えました | status は requires_payment_method で、last_payment_error が設定されます。 |
payment_method_microdeposit_verification_timeout | Webhook イベントを通じて非同期で発生 | 少額入金がタイムアウトになりました。顧客は要求された 10 日の期間内に銀行口座を確認しませんでした。 | status は requires_payment_method で、last_payment_error が設定されます。 |
PaymentIntent の成功を確認するサーバ側
カナダのプレオーソリデビットは、遅延通知型の支払い方法です。このため、顧客の口座から引き落としを開始してから、支払いの成功または失敗の通知を受けるまでに最大で 5 営業日かかります。
最初に作成する PaymentIntent のステータスは processing
となります。決済が成功すると、PaymentIntent のステータスは processing
から succeeded
に変わります。
PaymentIntent のステータスが更新されると、以下のイベントが送信されます。
イベント | 説明 | 次のステップ |
---|---|---|
payment_intent.processing | 顧客の支払いは、Stripe に正常に送信されました。 | 開始された支払いの成功、または失敗の結果を待ちます。 |
payment_intent.succeeded | 顧客の支払いが成功しました。 | 顧客が購入した商品またはサービスのフルフィルメントを行います。 |
payment_intent.payment_failed | 顧客の支払いは拒否されました。これは、少額入金確認の失敗に適用されることもあります。 | 顧客にメールまたはプッシュ通知で連絡し、別の支払い方法をリクエストします。少額入金確認の失敗のために Webhook が送信された場合には、ユーザは銀行口座情報をもう一度入力する必要があり、新しい少額入金がユーザの口座に対して行われます。 |
Webhook を使用して支払いが成功したことを確認し、顧客に支払い完了を通知することをお勧めします。Stripe ダッシュボードでイベントを表示することもできます。
組み込みをテストする
少額入金の確認メールを受信する
銀行口座の詳細を収集し、同意書を承認した後に、テスト環境で少額入金の確認メールを受信するには、支払い方法の詳細を確認する際に、payment_method[billing_details][email]
フィールドに {any_prefix}+test_email@{any_domain}
の形式でメールアドレスを指定します。
テスト用の口座番号
Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号をいくつか用意しています。支払いが自動的に成功または失敗するすべてのテスト用の口座は、以下のテスト用の少額入金を使用して確認してから設定を完了する必要があります。
銀行番号 | 支店番号 | 口座番号 | シナリオ |
---|---|---|---|
000 | 11000 | 000123456789 | 少額入金が確認された後、支払いが直ちに成功します。 |
000 | 11000 | 900123456789 | 少額入金が確認された後、3 分遅延してから支払いが成功します。 |
000 | 11000 | 000222222227 | 少額入金が確認された後、支払いが直ちに失敗します。 |
000 | 11000 | 900222222227 | 少額入金が確認された後、3 分遅延してから支払いが失敗します。 |
000 | 11000 | 000666666661 | 確認用の少額入金の送金が失敗します。 |
テスト環境で銀行口座確認の成功または失敗をデモンストレーションするには、少額入金に以下の特定の金額を使用してください。
少額入金の金額 | シナリオ |
---|---|
32 および 45 | 口座が無事に確認されます。 |
その他の任意の数字の組み合わせ | 口座の確認が失敗します。 |