# ACH ダイレクトデビットによる将来の支払いに備えて詳細を保存する 将来の ACH ダイレクトデビットによる支払いに備えて支払い方法の詳細を保存する方法を紹介します。 # Checkout > This is a Checkout for when payment-ui is checkout. View the full page at https://docs.stripe.com/payments/ach-direct-debit/set-up-payment?payment-ui=checkout. [設定モード](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-mode)の Checkout を使用して、事前に決済手段の詳細を収集し、後から最終的な金額や支払い日を決定できます。これは、次の場合に役立ちます。 - 決済手段をウォレットに保存して、以降の購入を効率化する - サービスの提供後に追加料金を回収する - *サブスクリプション* (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)の無料トライアルを開始する > ACH Direct Debit は、[遅延通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であるため、支払い後に資金はすぐには利用可能になりません。通常、決済金額がアカウントに入金されるまでに 4 営業日かかります。 ## Before you begin このガイドでは、Checkout の基本的な[将来の支払いを設定する](https://docs.stripe.com/payments/save-and-reuse.md?platform=web&ui=stripe-hosted)システムを拡張して、ACH Direct Debit による決済のサポートを追加する方法をご紹介します。 ## 顧客を作成または取得する [推奨] [サーバー側] > #### Use the Accounts v2 API to represent customers > > The Accounts v2 API is GA for Connect users, and in public preview for other Stripe users. All Stripe users can enable Accounts v2 [in their Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). However, when making calls to the Accounts v2 API, preview users need to [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定の Account オブジェクトとしてモデル化する](https://docs.stripe.com/connect/use-accounts-as-customers.md)ことをお勧めします。 #### Accounts v2 ユーザーがあなたのビジネスでアカウントを作成したときに、顧客が設定する [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) オブジェクトを作成するか、このユーザーに関連付けられた既存の `Account` を取得します。`Account` オブジェクトの ID を自社の顧客に関する内部表現に関連付けると、後で保存済みの決済手段の詳細を取得して利用できます。`Account` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "contact_email": "{{CUSTOMER_EMAIL}}" }' ``` #### Customers v1 ユーザーがあなたのビジネスでアカウントを作成したときに、*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` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} ``` ## 支払い方法として ACH ダイレクトデビットを有効にする 新しい [Checkout セッション](https://docs.stripe.com/api/checkout/sessions.md)を作成する際は、以下を行う必要があります。 1. `us_bank_account` を `payment_method_types` のリストに追加します。 1. `payment_method` を含めるように `permissions` パラメーターを設定します。 #### Stripe ホスト型ページ ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d mode=setup \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "success_url=https://example.com/success" ``` #### 組み込みフォーム ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d mode=setup \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://example.com/return" \ -d ui_mode=embedded_page ``` Financial Connections 手数料の詳細については、[料金体系の詳細](https://stripe.com/financial-connections#pricing)をご覧ください。 デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、[Financial Connections](https://docs.stripe.com/financial-connections.md) で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、[Financial Connections に関するドキュメント](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)をご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。 > 顧客がアカウントを認証した後で、追加データにアクセスを拡張するには、権限を拡張してアカウントを再度関連付ける必要があります。 Checkout セッションでは、顧客にダイアログが表示され、即時確認を使用するか、少額入金による確認のために銀行口座情報を入力するか選択することができます。 顧客が少額入金による確認を選択した場合、Stripe は指定された銀行口座に 2 回の少額入金を自動的に行います。これらの入金が顧客のオンライン銀行明細書に表示されるまでに 1 ～ 2 営業日かかります。入金が到着すると、金額を確定して Stripe で銀行口座を確認するためのリンクが記載されたメールが、顧客に届きます。確認が完了すると、決済の処理が開始されます。 ## 組み込みをテストする [Financial Connections](https://docs.stripe.com/financial-connections/testing.md#web-how-to-use-test-accounts) を使用して即時確認を行うシナリオをテストする方法をご紹介します。 ### サンドボックスで取引メールを送信する 銀行口座の詳細を収集し、同意書を受け付けたら、*サンドボックス* (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)で同意書の確認メールと少額入金の確認メールを送信します。 ドメインが **{domain}** で、ユーザー名が **{username}** の場合、メール形式 **{username}+test\_email@{domain}** を使用してテスト取引メールを送信します。 たとえば、ドメインが **example.com** でユーザー名が **info** の場合、ACH Direct Debit 決済のテストには **info+test\_email@example.com** という形式を使用します。この形式により、メールが正しくルーティングされます。**+test\_email** サフィックスを含めない場合、メールは送信されません。 > テスト中にこれらのメールをトリガーするには、[Stripe の本番環境利用の申請](https://docs.stripe.com/get-started/account/activate.md)を行う必要があります。 ### テスト用口座番号 Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号と対応するトークンをいくつか用意しています。 | 口座番号 | トークン | 金融番号 | 動作 | | -------------- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `000123456789` | `pm_usBankAccount_success` | `110000000` | 支払いは成功します。 | | `000111111113` | `pm_usBankAccount_accountClosed` | `110000000` | 口座が解約済みであるため、支払いは失敗します。 | | `000000004954` | `pm_usBankAccount_riskLevelHighest` | `110000000` | この支払いは、[不正利用のリスクが高い](https://docs.stripe.com/radar/risk-evaluation.md#high-risk)ため、Radar によってブロックされています。 | | `000111111116` | `pm_usBankAccount_noAccount` | `110000000` | 口座が見つからないため、支払いは失敗します。 | | `000222222227` | `pm_usBankAccount_insufficientFunds` | `110000000` | 残高不足のため、支払いは失敗します。 | | `000333333335` | `pm_usBankAccount_debitNotAuthorized` | `110000000` | 引き落としがオーソリされていないため、支払いは失敗します。 | | `000444444440` | `pm_usBankAccount_invalidCurrency` | `110000000` | 通貨が無効であるため、支払いは失敗します。 | | `000666666661` | `pm_usBankAccount_failMicrodeposits` | `110000000` | 支払いで少額入金の送金が失敗します。 | | `000555555559` | `pm_usBankAccount_dispute` | `110000000` | 支払いによって不審請求の申請が開始されています。 | | `000000000009` | `pm_usBankAccount_processing` | `110000000` | 支払いは無期限に処理中のままになります。 [PaymentIntent キャンセル](https://docs.stripe.com/api/payment_intents/cancel.md) をテストするのに役立ちます。 | | `000777777771` | `pm_usBankAccount_weeklyLimitExceeded` | `110000000` | 支払い額がアカウントの週次支払い額の上限を超えているため、支払いが失敗しました。 | | `000888888885` | | `110000000` | [トークン化されたアカウント番号](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md)が無効化されると決済が失敗します。 | テスト取引を完了する前に、自動的に支払いに成功または失敗するテスト用のすべての口座を確認する必要があります。確認するには、下記の少額入金のテスト用の金額または明細書表記コードを使用します。 ### 少額入金の金額と明細書表記コードをテストする さまざまなシナリオを再現するために、これらの少額入金の金額「または」明細書表記コードの値 0.01 を使用します。 | 少額入金の金額 | 明細書表記コードの値 0.01 | シナリオ | | ------------- | --------------- | ------------------------- | | `32` および `45` | SM11AA | アカウントの確認をシミュレーションします。 | | `10` および `11` | SM33CC | 許容された確認回数の超過をシミュレーションします。 | | `40` および `41` | SM44DD | 少額入金のタイムアウトをシミュレーションします。 | ### 売上処理の動作をテストする テスト取引は即座に売上として処理され、利用可能なテスト残高に追加されます。この動作は、利用可能な残高で取引が売上として処理されるまでに[数日](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#timing)かかることがある、本番環境とは異なります。 ## 支払い方法を使用する Checkout セッションが完了すると、[PaymentMethod](https://docs.stripe.com/api/payment_methods.md) ID を[収集](https://docs.stripe.com/payments/checkout/save-and-reuse.md?payment-ui=stripe-hosted#retrieve-checkout-session)できます。これらの PaymentMethod ID を使用することで、顧客に銀行口座の再入力を求めることなく、将来の決済を開始できます。 [PaymentIntent を作成](https://docs.stripe.com/api/payment_intents/create.md)するときに、`payment_method` と顧客 ID を指定し、保存済みの銀行口座情報を使用して顧客に請求します。 ## Optional: 即時の確認のみ ACH ダイレクトデビットによる決済では、デフォルトで顧客は銀行口座の即時確認、または少額入金を使用できます。オプションとして、Checkout セッションを作成するときに `payment_method_options[us_bank_account][verification_method]` パラメーターを使用して、銀行口座の即時確認のみを要求するように設定することもできます。 #### Accounts v2 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \ --data-urlencode "success_url=https://example.com/success" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \ --data-urlencode "success_url=https://example.com/success" ``` ## Optional: Financial Connections 銀行口座のデータにアクセスする SetupIntentの作成時に、追加の[データ権限](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions)をリクエストする場合にのみ、Financial Connections データにアクセスできます。 顧客が[Stripe Financial Connections 認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を完了すると、返される `us_bank_account` PaymentMethod には、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md)を指す [financial_connections_account](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-us_bank_account-financial_connections_account) ID が含まれます。この ID を使用して口座データにアクセスします。 > 顧客が手動入力および少額入金によって関連付けた銀行口座には、Payment Method の `financial_connections_account` ID がありません。 Financial Connections アカウント ID を特定するには、SetupIntent を取得して `payment_method` 属性を拡張します。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUPINTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` ```json { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", // ... "type": "us_bank_account" "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK","financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", "fingerprint": "q9qchffggRjlX2tb", "last4": "6789", "routing_number": "110000000" } } // ... } ``` 残高データにアクセスできる場合には、収集した支払い方法で支払いを開始する前に[残高を確認する](https://docs.stripe.com/financial-connections/balances.md#initiate-balance-refresh)ことをお勧めします。 追加の口座データを使用して、[Financial Connections](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#optimize) で ACH の実装を最適化する方法をご紹介します。 ## Optional: デフォルトの支払い方法を更新する `SetupIntent` が `succeeded` 状態に達すると、顧客の `default_payment_method` を更新できます。 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' if event.type == 'setup_intent.succeeded' setup_intent = event.data.object customer_id = setup_intent['customer'] payment_method_id = setup_intent['payment_method'] # Set the default payment method Stripe::Customer.update( customer_id, { invoice_settings: { default_payment_method: payment_method_id } } ) end ``` # Elements > This is a Elements for when payment-ui is elements. View the full page at https://docs.stripe.com/payments/ach-direct-debit/set-up-payment?payment-ui=elements. [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)の無料トライアルを開始する > ACH Direct Debit は、[遅延通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であるため、支払い後に資金はすぐには利用可能になりません。通常、決済金額がアカウントに入金されるまでに 4 営業日かかります。 ## 顧客を作成または取得する [推奨] [サーバー側] > #### Use the Accounts v2 API to represent customers > > The Accounts v2 API is GA for Connect users, and in public preview for other Stripe users. All Stripe users can enable Accounts v2 [in their Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). However, when making calls to the Accounts v2 API, preview users need to [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定の Account オブジェクトとしてモデル化する](https://docs.stripe.com/connect/use-accounts-as-customers.md)ことをお勧めします。 #### Accounts v2 ユーザーがあなたのビジネスでアカウントを作成したときに、顧客が設定する [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) オブジェクトを作成するか、このユーザーに関連付けられた既存の `Account` を取得します。`Account` オブジェクトの ID を自社の顧客に関する内部表現に関連付けると、後で保存済みの決済手段の詳細を取得して利用できます。`Account` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "contact_email": "{{CUSTOMER_EMAIL}}" }' ``` #### Customers v1 ユーザーがあなたのビジネスでアカウントを作成したときに、*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` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} ``` ## SetupIntent を作成する [サーバー側] [SetupIntent](https://docs.stripe.com/api/setup_intents.md) は、将来の支払いに備えて顧客の決済手段を設定する意図を示すオブジェクトです。`SetupIntent` は、この設定プロセスの手順を追跡します。 [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) を us_bank_account に設定してサーバーで SetupIntent を作成し、Customer の [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) を指定します。 Financial Connections 手数料の詳細については、[料金体系の詳細](https://stripe.com/financial-connections#pricing)をご覧ください。 デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、[Financial Connections](https://docs.stripe.com/financial-connections.md) で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、[Financial Connections に関するドキュメント](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)をご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。 > 顧客がアカウントを認証した後で、追加データにアクセスを拡張するには、権限を拡張してアカウントを再度関連付ける必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` ### 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
``` ```ruby get '/checkout' do @intent = # ... Fetch or create the SetupIntent erb :checkout end ``` ## 支払い方法の詳細を収集する [クライアント側] 顧客が ACH Direct Debitでの支払いをクリックしたときに、Stripe.js を使用してその支払いを Stripe に送信することをお勧めします。[Stripe.js](https://docs.stripe.com/payments/elements.md) は、決済フローを構築するための Stripe の基本的な JavaScript ライブラリです。これにより、実装に関する複雑な処理が自動的に行われ、将来、他の決済手段にも対応できるように実装を簡単に拡張できます。 Stripe.js スクリプトを決済ページに含めるには、このスクリプトを HTML ファイルの `head` に追加します。 ```html Checkout ``` 決済ページで以下の 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('<>'); ``` 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)) を使用します。これは、Stripe API リクエストを認証する API キーとは異なります。 client secret は Payment Method の設定プロセスを完了できるため、慎重に取り扱う必要があります。記録したり、URL に埋め込んだり、当該の顧客以外に漏洩することがないようにしてください。 [stripe.collectBankAccountForSetup](https://docs.stripe.com/js/setup_intents/collect_bank_account_for_setup) を使用して、[Financial Connections](https://docs.stripe.com/financial-connections.md) で銀行口座の詳細を収集し、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) を作成して SetupIntent に関連付けます。ACH ダイレクトデビットの PaymentMethod を作成するには、`billing_details` パラメーターに口座名義人を含める必要があります。 ```javascript // Use the form that already exists on the web page. const paymentMethodForm = document.getElementById('payment-method-form'); const confirmationForm = document.getElementById('confirmation-form'); paymentMethodForm.addEventListener('submit', (ev) => { ev.preventDefault(); const accountHolderNameField = document.getElementById('account-holder-name-field'); const emailField = document.getElementById('email-field'); // Calling this method will open the instant verification dialog. stripe.collectBankAccountForSetup({ clientSecret: clientSecret, params: { payment_method_type: 'us_bank_account', payment_method_data: { billing_details: { name: accountHolderNameField.value, email: emailField.value, }, }, }, expand: ['payment_method'], }) .then(({setupIntent, error}) => { if (error) { console.error(error.message); // PaymentMethod collection failed for some reason. } else if (setupIntent.status === 'requires_payment_method') { // Customer canceled the hosted verification modal. Present them with other // payment method type options. } else if (setupIntent.status === 'requires_confirmation') { // We collected an account - possibly instantly verified, but possibly // manually-entered. Display payment method details and mandate text // to the customer and confirm the intent once they accept // the mandate. confirmationForm.show(); } }); }); ``` [Financial Connections 認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)では、銀行口座の詳細の収集と確認を自動的に処理します。顧客が認証フローを完了すると、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が自動的に SetupIntent に関連付けられ、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md)が作成されます。 > 手動入力と少額入金によって顧客が関連付けた銀行口座では、残高、所有権、取引などの追加の銀行口座データにアクセスできません。 すべてのデバイスで最適なユーザー体験を提供できるように、ビューポートの `meta` タグを使用して、ページのビューポートの `minimum-scale` を 1 に設定します。 ```html ``` ## Optional: Financial Connections 銀行口座のデータにアクセスする [サーバー側] SetupIntentの作成時に、追加の[データ権限](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions)をリクエストする場合にのみ、Financial Connections データにアクセスできます。 顧客が[Stripe Financial Connections 認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を完了すると、返される `us_bank_account` PaymentMethod には、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md)を指す [financial_connections_account](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-us_bank_account-financial_connections_account) ID が含まれます。この ID を使用して口座データにアクセスします。 > 顧客が手動入力および少額入金によって関連付けた銀行口座には、Payment Method の `financial_connections_account` ID がありません。 Financial Connections アカウント ID を特定するには、SetupIntent を取得して `payment_method` 属性を拡張します。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUPINTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` ```json { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", // ... "type": "us_bank_account" "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK","financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", "fingerprint": "q9qchffggRjlX2tb", "last4": "6789", "routing_number": "110000000" } } // ... } ``` 残高データにアクセスできる場合には、収集した支払い方法で支払いを開始する前に[残高を確認する](https://docs.stripe.com/financial-connections/balances.md#initiate-balance-refresh)ことをお勧めします。 追加の口座データを使用して、[Financial Connections](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#optimize) で ACH の実装を最適化する方法をご紹介します。 ## 同意書承認を収集し送信する [クライアント側] SetupIntent を完了して顧客の支払い方法の詳細を保存する前に、顧客に同意書の規約を表示して、顧客から承認を得る必要があります。 Nacha の運営規則に準拠するため、決済を開始する前に、同意書の規約を表示して顧客から承認を得る必要があります。[同意書](https://docs.stripe.com/payments/ach-direct-debit.md#mandates)の詳細については、こちらの記事をご覧ください。 顧客が同意書の規約を承認する場合、SetupIntent を確定する必要があります。顧客がフォームを送信したら、[stripe.confirmUsBankAccountSetup](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) を使用して支払いを完了します。 ```javascript confirmationForm.addEventListener('submit', (ev) => { ev.preventDefault(); stripe.confirmUsBankAccountSetup(clientSecret) .then(({setupIntent, error}) => { if (error) { console.error(error.message); // The payment failed for some reason. } else if (setupIntent.status === "requires_payment_method") { // Confirmation failed. Attempt again with a different payment method. } else if (setupIntent.status === "succeeded") { // Confirmation succeeded! The account is now saved. // Display a message to customer. } else if (setupIntent.next_action?.type === "verify_with_microdeposits") { // The account needs to be verified through microdeposits. // Display a message to consumer with next steps (consumer waits for // microdeposits, then enters a statement descriptor code on a page sent to them through email). } }); }); ``` > [stripe.confirmUsBankAccountSetup](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) の完了には数秒かかる場合があります。この間、フォームが再送信されないように無効化し、待機中のインジケーター (スピナーなど) を表示します。エラーが発生した場合は、それを顧客に表示し、フォームを再度有効化し、待機中のインジケーターを非表示にします。 成功した場合、Stripe から以下のいずれかのステータスで SetupIntent オブジェクトが返されます。 | ステータス | 説明 | 次のステップ | | ----------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `succeeded` | 銀行口座が即座に確認されたか、確認が必要ありませんでした。 | アクションは不要です | | `requires_action` | 銀行口座の確認を完了するには、追加のアクションが必要です。 | ステップ 6: [少額入金で銀行口座を確認する](https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment.md#web-verify-with-microdeposits) | SetupIntent の確定に成功した後、同意書の確認メールと収集した銀行口座情報を顧客に送信する必要があります。Stripe はデフォルトでこれらの処理を行いますが、ご希望に応じて[カスタム通知の送信](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails)を選択することもできます。 ## 少額入金で銀行口座を確認する [クライアント側] すべての顧客が銀行口座を即時に確認できるわけではありません。このステップは、顧客が前のステップで即時確認フローからオプトアウトした場合にのみ適用されます。 このような場合、Stripe は `descriptor_code` による少額入金を送金し、銀行口座の確認でさらに問題が発生した場合には、`amount` による少額入金に戻る場合があります。これらの入金が顧客のオンライン明細書に表示されるには 1 ～ 2 営業日かかります。 - **明細書表記コード**。SM で始まる一意の 6 桁の `descriptor_code` を指定して、0.01 USD の 1 件の少額入金を顧客の銀行口座に送金します。顧客は、この文字列を使用して、銀行口座を確認します。 - **金額**。Stripe は、`ACCTVERIFY` という明細書表記を使用し、一意でない 2 件の少額入金を顧客の銀行口座に送金します。顧客は、この入金額を使用して銀行口座を確認します。 前のステップの [stripe.confirmUsBankAccountSetup](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) メソッドの呼び出しの結果として、`requires_action` 状態の SetupIntent が返されます。この SetupIntent には、確認を完了するための有益な情報を含む `next_action` フィールドが含まれています。 ```javascript next_action: { type: "verify_with_microdeposits", verify_with_microdeposits: { arrival_date: 1647586800, hosted_verification_url: "https://payments.stripe.com/…", microdeposit_type: "descriptor_code" } } ``` [請求書メール](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-billing_details-email)を指定した場合、Stripe はこのメールで入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了することができます。 > 確認の失敗は、明細書表記ベースの少額入金の場合は 10 回、金額ベースの少額入金の場合は 3 回までです。この上限を超えると、Stripe は銀行口座を確認できなくなります。また、少額入金の確認は 10 日経過するとタイムアウトになります。この期間内に少額入金を確認できなかった場合、SetupIntent は新しい支払い方法の詳細を要求する状態に戻ります。少額入金とは何か、どのように使用されるのかを顧客に明確に伝えることで、確認に関する問題を回避できます。 ### オプション: カスタムのメール通知を送信する 必要に応じて、顧客に[カスタムのメール通知](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails)を送信することができます。カスタムメールを設定した後は、顧客が確認メールに応答する方法を指定する必要があります。以下の方法のうち、いずれか _1 つ_を指定してください。 - Stripe 上のオンライン確認ページを使用します。これを行うには、[next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-verify_with_microdeposits-hosted_verification_url) オブジェクトの `verify_with_microdeposits[hosted_verification_url]` URL を使用し、顧客に確認プロセスを完了するよう指示します。 - Stripe がオンラインで提供する確認ページを使用しない場合、ご自身のサイトにフォームを作成します。顧客はこのフォームを使用して少額入金の金額を伝え、[Stripe.js](https://docs.stripe.com/js/payment_intents/verify_microdeposits_for_payment) を使用して、銀行口座を確認します。 - 確認のために、少なくとも 6 桁のストリングの `descriptor code` パラメーターを処理するフォームを設定します。 - また Stripe では、`amounts` パラメーターも処理するようにフォームを設定することをお勧めします。これはこのパラメーターが、顧客が利用する一部の銀行で必要とされることがあるためです。 組み込みは、`descriptor_code` 「または」 `amounts` でのみ渡されます。組み込みでどちらが使用されているかを判断するには、`next_action` オブジェクトの `verify_with_microdeposits[microdeposit_type]` の値を確認します。 ```javascript stripe.verifyMicrodepositsForSetup(clientSecret, { // Provide either a descriptor_code OR amounts, not both descriptor_code: `SMT86W`, amounts: [32, 45], }); ``` 銀行口座の確認に成功すると、Stripe は SetupIntent オブジェクトを `succeeded` の `status` で返し、[setup_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-setup_intent.succeeded) *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) イベントを送信します。 確認が失敗する原因はいくつか存在します。失敗は直接的なエラー応答として同期的に発生することも、[setup_intent.setup_failed](https://docs.stripe.com/api/events/types.md#event_types-setup_intent.setup_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` が設定されます。 | ## 組み込みをテストする [Financial Connections](https://docs.stripe.com/financial-connections/testing.md#web-how-to-use-test-accounts) を使用して即時確認を行うシナリオをテストする方法をご紹介します。 ### サンドボックスで取引メールを送信する 銀行口座の詳細を収集し、同意書を受け付けたら、*サンドボックス* (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)で同意書の確認メールと少額入金の確認メールを送信します。 ドメインが **{domain}** で、ユーザー名が **{username}** の場合、メール形式 **{username}+test\_email@{domain}** を使用してテスト取引メールを送信します。 たとえば、ドメインが **example.com** でユーザー名が **info** の場合、ACH Direct Debit 決済のテストには **info+test\_email@example.com** という形式を使用します。この形式により、メールが正しくルーティングされます。**+test\_email** サフィックスを含めない場合、メールは送信されません。 > テスト中にこれらのメールをトリガーするには、[Stripe の本番環境利用の申請](https://docs.stripe.com/get-started/account/activate.md)を行う必要があります。 ### テスト用口座番号 Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号と対応するトークンをいくつか用意しています。 | 口座番号 | トークン | 金融番号 | 動作 | | -------------- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `000123456789` | `pm_usBankAccount_success` | `110000000` | 支払いは成功します。 | | `000111111113` | `pm_usBankAccount_accountClosed` | `110000000` | 口座が解約済みであるため、支払いは失敗します。 | | `000000004954` | `pm_usBankAccount_riskLevelHighest` | `110000000` | この支払いは、[不正利用のリスクが高い](https://docs.stripe.com/radar/risk-evaluation.md#high-risk)ため、Radar によってブロックされています。 | | `000111111116` | `pm_usBankAccount_noAccount` | `110000000` | 口座が見つからないため、支払いは失敗します。 | | `000222222227` | `pm_usBankAccount_insufficientFunds` | `110000000` | 残高不足のため、支払いは失敗します。 | | `000333333335` | `pm_usBankAccount_debitNotAuthorized` | `110000000` | 引き落としがオーソリされていないため、支払いは失敗します。 | | `000444444440` | `pm_usBankAccount_invalidCurrency` | `110000000` | 通貨が無効であるため、支払いは失敗します。 | | `000666666661` | `pm_usBankAccount_failMicrodeposits` | `110000000` | 支払いで少額入金の送金が失敗します。 | | `000555555559` | `pm_usBankAccount_dispute` | `110000000` | 支払いによって不審請求の申請が開始されています。 | | `000000000009` | `pm_usBankAccount_processing` | `110000000` | 支払いは無期限に処理中のままになります。 [PaymentIntent キャンセル](https://docs.stripe.com/api/payment_intents/cancel.md) をテストするのに役立ちます。 | | `000777777771` | `pm_usBankAccount_weeklyLimitExceeded` | `110000000` | 支払い額がアカウントの週次支払い額の上限を超えているため、支払いが失敗しました。 | | `000888888885` | | `110000000` | [トークン化されたアカウント番号](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md)が無効化されると決済が失敗します。 | テスト取引を完了する前に、自動的に支払いに成功または失敗するテスト用のすべての口座を確認する必要があります。確認するには、下記の少額入金のテスト用の金額または明細書表記コードを使用します。 ### 少額入金の金額と明細書表記コードをテストする さまざまなシナリオを再現するために、これらの少額入金の金額「または」明細書表記コードの値 0.01 を使用します。 | 少額入金の金額 | 明細書表記コードの値 0.01 | シナリオ | | ------------- | --------------- | ------------------------- | | `32` および `45` | SM11AA | アカウントの確認をシミュレーションします。 | | `10` および `11` | SM33CC | 許容された確認回数の超過をシミュレーションします。 | | `40` および `41` | SM44DD | 少額入金のタイムアウトをシミュレーションします。 | ### 売上処理の動作をテストする テスト取引は即座に売上として処理され、利用可能なテスト残高に追加されます。この動作は、利用可能な残高で取引が売上として処理されるまでに[数日](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#timing)かかることがある、本番環境とは異なります。 ## 将来の決済を受け付ける [サーバー側] SetupIntent が成功すると、新しい *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が作成され [Customer](https://docs.stripe.com/api/customers.md) に関連付けられます。これらは、顧客に銀行口座の入力を再度求めることなく将来の支払いを開始するために使用されます。 #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "amount"=1099 \ -d "currency"="usd" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "payment_method"="{{PAYMENT_METHOD_ID}}" \ -d "payment_method_types[]"="us_bank_account" \ -d "confirm"="true" ``` ## Optional: 即時の確認のみ [サーバー側] デフォルトでは、アメリカの銀行口座による決済手段を設定すると、顧客は銀行口座の即時確認、または少額入金を使用できます。SetupIntent を作成するときに、[verification_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method_options-us_bank_account-verification_method) パラメーターを使用して、銀行口座の即時確認のみを必要に応じて要求することができます。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` これにより、少額入金の確認を処理する必要はなくなりますが、即時確認に失敗した場合は、SetupIntent のステータスは、顧客の銀行口座の即時確認に失敗したことを示す `requires_payment_method` となります。 ## Optional: 少額入金のみによる確認 [サーバー側] デフォルトでは、顧客はアメリカの銀行口座を使用する決済手段を設定することで、銀行口座の即時確認、または少額入金を実行できます。SetupIntent を作成するときに、[verification_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method_options-us_bank_account-verification_method) パラメーターを使用して、少額入金の確認を必要に応じて要求することができます。 > カスタムの決済フォームを使用している場合、自社の UI を構築して銀行口座の詳細を収集する必要があります。Stripe の少額入金に関するメールを無効にしている場合は、少額入金のコードまたは金額を確認するために顧客用の自社の UI を構築する必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=microdeposits" ``` 独自のフォームで顧客の銀行口座を収集した後、その詳細を使用して [stripe.confirmUsBankAccountSetup](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) を呼び出し、SetupIntent を完了します。 ```javascript var form = document.getElementById('payment-form'); var accountholderName = document.getElementById('accountholder-name'); var email = document.getElementById('email'); var accountNumber = document.getElementById('account-number'); var routingNumber = document.getElementById('routing-number'); var accountHolderType= document.getElementById('account-holder-type'); var submitButton = document.getElementById('submit-button'); var clientSecret = submitButton.dataset.secret; form.addEventListener('submit', function(event) { event.preventDefault(); stripe.confirmUsBankAccountSetup(clientSecret, { payment_method: { billing_details: { name: accountholderName.value, email: email.value, }, us_bank_account: { account_number: accountNumber.value, routing_number: routingNumber.value, account_holder_type: accountHolderType.value, // 'individual' or 'company' }, }, }) .then({setupIntent, error} => { if (error) { // Inform the customer that there was an error. console.log(error.message); } else { // Handle next step based on the intent's status. console.log("SetupIntent ID: " + setupIntent.id); console.log("SetupIntent status: " + setupIntent.status); } }); }); ``` ## Optional: デフォルトの支払い方法を更新する [サーバー側] `SetupIntent` が `succeeded` 状態に達すると、顧客の `default_payment_method` を更新できます。 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' if event.type == 'setup_intent.succeeded' setup_intent = event.data.object customer_id = setup_intent['customer'] payment_method_id = setup_intent['payment_method'] # Set the default payment method Stripe::Customer.update( customer_id, { invoice_settings: { default_payment_method: payment_method_id } } ) end ``` # iOS > This is a iOS for when payment-ui is mobile and platform is ios. View the full page at https://docs.stripe.com/payments/ach-direct-debit/set-up-payment?payment-ui=mobile&platform=ios. [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)の無料トライアルを開始する > ACH Direct Debit は、[遅延通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であるため、支払い後に資金はすぐには利用可能になりません。通常、決済金額がアカウントに入金されるまでに 4 営業日かかります。 [iOS SDK](https://github.com/stripe/stripe-ios) はオープンソースです。[詳細なドキュメントが提供されており](https://stripe.dev/stripe-ios/index.html)、iOS 13 以降をサポートするアプリと互換性があります。 #### Swift Package Manager SDK をインストールするには、以下のステップに従います。 1. Xcode で、**File (ファイル)** > **Add Package Dependencies… (パッケージ依存関係を追加)** を選択し、リポジトリー URL として `https://github.com/stripe/stripe-ios-spm` を入力します。 1. [リリースページ](https://github.com/stripe/stripe-ios/releases)から最新のバージョン番号を選択します。 1. **StripePayments** と **StripeFinancialConnections** 製品を[アプリのターゲット](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app)に追加します。 #### CocoaPods 1. まだインストールしていない場合は、[CocoaPods](https://guides.cocoapods.org/using/getting-started.html) の最新バージョンをインストールします。 1. 既存の [Podfile](https://guides.cocoapods.org/syntax/podfile.html) がない場合は、以下のコマンドを実行して作成します。 ```bash pod init ``` 1. この行を `Podfile` に追加します。 ```podfile pod 'Stripe' pod 'StripeFinancialConnections' ``` 1. 以下のコマンドを実行します。 ```bash pod install ``` 1. これ以降は、Xcode でプロジェクトを開く際に、`.xcodeproj` ファイルではなく、必ず `.xcworkspace` ファイルを使用するということを忘れないでください。 1. 今後、SDK の最新バージョンに更新するには、以下を実行します。 ```bash pod update Stripe pod update StripeFinancialConnections ``` #### Carthage 1. まだインストールしていない場合は、[Carthage](https://github.com/Carthage/Carthage#installing-carthage) の最新バージョンをインストールします。 1. この行を `Cartfile` に追加します。 ```cartfile github "stripe/stripe-ios" ``` 1. [Carthage のインストール手順](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos)に従います。必ず、[こちら](https://github.com/stripe/stripe-ios#releases)にリストされている必要なフレームワークのすべてを埋め込んでください。 1. 上記のリンクで必要とされるフレームワークに加え、フレームワーク **StripeFinancialConnections** も忘れずに追加してください。 1. 今後、SDK の最新バージョンに更新するには、以下のコマンドを実行します。 ```bash carthage update stripe-ios --platform ios ``` #### 手動のフレームワーク 1. Stripe の [GitHub リリースページ](https://github.com/stripe/stripe-ios/releases/latest)に移動して、**Stripe.xcframework.zip** をダウンロードして解凍します。 1. **Stripe.xcframework** を、Xcode プロジェクトの **General (一般) ** 設定の **Embedded Binaries (埋め込みバイナリ)** セクションにドラッグします。**Copy items if needed (必要に応じてアイテムをコピーする)** を必ず選択してください。 1. **StripeFinancialConnections.xcframework** に対し、ステップ 2 を繰り返します。 1. [こちら](https://github.com/stripe/stripe-ios#releases)にリストされている必要なフレームワークのすべてに対して、ステップ 2 を繰り返します。 1. 今後、Stripe の SDK の最新バージョンに更新するには、ステップ 1 ～ 3 を繰り返します。 > 最新の SDK リリースと過去のバージョンの詳細については、GitHub の[リリース](https://github.com/stripe/stripe-ios/releases) ページをご覧ください。新しいリリースの公開時に通知を受け取るには、[リポジトリーのリリースを確認してください](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository)。 アプリの起動時に Stripe [公開可能キー](https://dashboard.stripe.com/test/apikeys)を使用して SDK を設定します。これにより、アプリが Stripe API にリクエストを送信できるようになります。 #### Swift ```swift import UIKitimportStripeFinancialConnections @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<>" // do any other necessary launch configuration return true } } ``` > テストおよび開発時には[テストキー](https://docs.stripe.com/keys.md#obtain-api-keys)を使用し、アプリの公開時には[本番環境](https://docs.stripe.com/keys.md#test-live-modes)キーを使用します。 ## 顧客を作成または取得する [推奨] [サーバー側] > #### Use the Accounts v2 API to represent customers > > The Accounts v2 API is GA for Connect users, and in public preview for other Stripe users. All Stripe users can enable Accounts v2 [in their Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). However, when making calls to the Accounts v2 API, preview users need to [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定の Account オブジェクトとしてモデル化する](https://docs.stripe.com/connect/use-accounts-as-customers.md)ことをお勧めします。 #### Accounts v2 ユーザーがあなたのビジネスでアカウントを作成したときに、顧客が設定する [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) オブジェクトを作成するか、このユーザーに関連付けられた既存の `Account` を取得します。`Account` オブジェクトの ID を自社の顧客に関する内部表現に関連付けると、後で保存済みの決済手段の詳細を取得して利用できます。`Account` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "contact_email": "{{CUSTOMER_EMAIL}}" }' ``` #### Customers v1 ユーザーがあなたのビジネスでアカウントを作成したときに、*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` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} ``` ## SetupIntent を作成する [サーバー側] [クライアント側] [SetupIntent](https://docs.stripe.com/api/setup_intents.md) は、将来の支払いに備えて顧客の決済手段を設定する意図を示すオブジェクトです。`SetupIntent` は、この設定プロセスの手順を追跡します。 ### サーバー側 [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) を us_bank_account に設定してサーバーで SetupIntent を作成し、Customer の [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) を指定します。 Financial Connections 手数料の詳細については、[料金体系の詳細](https://stripe.com/financial-connections#pricing)をご覧ください。 デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、[Financial Connections](https://docs.stripe.com/financial-connections.md) で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、[Financial Connections に関するドキュメント](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)をご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。 > 顧客がアカウントを認証した後で、追加データにアクセスを拡張するには、権限を拡張してアカウントを再度関連付ける必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` ### クライアント側 返された 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)) が含まれています。これは、SetupIntent オブジェクト全体を渡すことなく安全に設定を完了するために、クライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。 #### Swift ```swift import UIKit import StripePayments class CheckoutViewController: UIViewController { var setupIntentClientSecret: String? func startCheckout() { // Request a SetupIntent from your server and store its client secret } }} ``` ## 戻り先 URL を設定する [クライアント側] 顧客はお客様のアプリから離れて、(Safari やバンキングアプリなどで) 認証する場合があります。ユーザーが認証後にアプリに自動的に戻れるようにするには、[カスタム URL スキームを構成](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)し、URL を SDK に転送するようにアプリのデリゲートを設定します。Stripe は[ユニバーサルリンク](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content)には対応していません。 > Stripe は、指定された戻り先 URL にパラメーターを追加する場合があります。パラメーターが追加された戻り先 URL がコードで拒否されないことを確認してください。 #### SceneDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { guard let url = URLContexts.first?.url else { return } let stripeHandled = StripeAPI.handleURLCallback(with: url) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } ``` #### AppDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { let stripeHandled = StripeAPI.handleURLCallback(with: url) if (stripeHandled) { return true } else { // This was not a Stripe url – handle the URL normally as you would } return false } ``` #### SwiftUI #### Swift ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { Text("Hello, world!").onOpenURL { incomingURL in let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } } } } ``` ## 支払い方法の詳細を収集する [クライアント側] ACH ダイレクトデビットで SetupIntent を成功させるには、顧客の氏名と (オプションで) メールアドレスが必要です。アプリで、必要な請求詳細を顧客から収集してください。 - 顧客の氏名 (姓と名) - 顧客のメールアドレス `STPCollectBankAccountParams` でクラス関数 `collectUSBankAccountParams` を使用し、`collectBankAccountForSetup` を呼び出すために必要なパラメーターを作成します。 `BankAccountCollector` のインスタンスを作成して `collectBankAccountForSetup` を呼び出し、銀行口座情報を収集し、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) を作成し、その PaymentMethod を SetupIntent に関連付けます。ACH Direct Debit PaymentMethod を作成するには、`billing_details` パラメーターに口座名義人を含める必要があります。 #### Swift ```swift // Build params let collectParams = STPCollectBankAccountParams.collectUSBankAccountParams(with: name, email: email) // Calling this method will display a modal for collecting bank account information let bankAccountCollector = STPBankAccountCollector() bankAccountCollector.collectBankAccountForSetup(clientSecret: clientSecret, returnURL: "https://your-app-domain.com/stripe-redirect", params: collectParams, from: self) { intent, error in guard let intent = intent else { // handle error return } if case .requiresPaymentMethod = intent.status { // Customer canceled the Financial Connections modal. Present them with other // payment method type options. } else if case .requiresConfirmation = intent.status { // We collected an account - possibly instantly verified, but possibly // manually-entered. Display payment method details and mandate text // to the customer and confirm the intent once they accept // the mandate. } } ``` これにより、銀行口座の詳細の収集と確認を処理するモーダル UI が読み込まれます。処理が完了すると、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が SetupIntent に自動的に関連付けられます。 ## Optional: Financial Connections 銀行口座のデータにアクセスする [サーバー側] SetupIntentの作成時に、追加の[データ権限](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions)をリクエストする場合にのみ、Financial Connections データにアクセスできます。 顧客が[Stripe Financial Connections 認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を完了すると、返される `us_bank_account` PaymentMethod には、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md)を指す [financial_connections_account](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-us_bank_account-financial_connections_account) ID が含まれます。この ID を使用して口座データにアクセスします。 > 顧客が手動入力および少額入金によって関連付けた銀行口座には、Payment Method の `financial_connections_account` ID がありません。 Financial Connections アカウント ID を特定するには、SetupIntent を取得して `payment_method` 属性を拡張します。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUPINTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` ```json { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", // ... "type": "us_bank_account" "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK","financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", "fingerprint": "q9qchffggRjlX2tb", "last4": "6789", "routing_number": "110000000" } } // ... } ``` 残高データにアクセスできる場合には、収集した支払い方法で支払いを開始する前に[残高を確認する](https://docs.stripe.com/financial-connections/balances.md#initiate-balance-refresh)ことをお勧めします。 追加の口座データを使用して、[Financial Connections](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#optimize) で ACH の実装を最適化する方法をご紹介します。 ## 同意書承認を収集し送信する [クライアント側] SetupIntent を完了して顧客の支払い方法の詳細を保存する前に、同意書の規約を表示して顧客から承認を得る必要があります。 *Nacha* (Nacha is the governing body that oversees the ACH network) の運営規則に準拠するため、決済を開始する前に、同意書の規約を表示して顧客から承認を得る必要があります。[同意書](https://docs.stripe.com/payments/ach-direct-debit.md#mandates)の詳細については、こちらの記事をご覧ください。 顧客が同意書の規約を承認する際に、お客様は SetupIntent を確定する必要があります。顧客がフォームを送信したら、`confirmSetupIntent` を使用して、決済を完了します。 #### Swift ```swift let setupIntentParams = STPSetupIntentConfirmParams(clientSecret: clientSecret, paymentMethodType: .USBankAccount) STPPaymentHandler.shared().confirmSetupIntent( setupIntentParams, with: self ) { (status, intent, error) in switch status { case .failed: // Payment failed case .canceled: // Payment was canceled case .succeeded: // Payment succeeded @unknown default: fatalError() } } ``` > `confirmSetupIntent` が完了するまでには数秒かかる場合があります。この間、フォームが再送信されないように無効化し、待機中のインジケーター (スピナーなど) を表示します。エラーが発生した場合は、それを顧客に表示し、フォームを再度有効化し、待機中のインジケーターを非表示にします。 成功した場合、Stripe から以下のいずれかのステータスで SetupIntent オブジェクトが返されます。 | ステータス | 説明 | 次のステップ | | ----------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `succeeded` | 銀行口座が即座に確認されたか、確認が必要ありませんでした。 | アクションは不要です | | `requires_action` | 銀行口座の確認を完了するには、追加のアクションが必要です。 | ステップ 6: [少額入金で銀行口座を確認する](https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment.md#ios-verify-with-microdeposits) | SetupIntent の確定に成功した後、同意書の確認メールと収集した銀行口座情報を顧客に送信する必要があります。Stripe はデフォルトでこれらの処理を行いますが、ご希望に応じて[カスタム通知の送信](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails)を選択することもできます。 ## 少額入金で銀行口座を確認する [クライアント側] すべての顧客が銀行口座を即座に確認できるわけではありません。このステップは、顧客が前のステップで即時確認フローからオプトアウトした場合にのみ適用されます。 このような場合、Stripe は `descriptor_code` による少額入金を送金し、銀行口座の確認でさらに問題が発生した場合には、`amount` による少額入金に戻る場合があります。これらの入金が顧客のオンライン明細書に表示されるには 1 ～ 2 営業日かかります。 - **明細書表記コード**。Stripe は、SM で始まる一意の 6 桁の `descriptor_code` を使用し、0.01 USD の 1 件の少額入金を顧客の銀行口座に送金します。顧客は、この文字列を使用して銀行口座を確認します。 - **金額**。Stripe は、`ACCTVERIFY` という明細書表記を使用し、一意でない 2 件の少額入金を顧客の銀行口座に送金します。顧客は、この入金額を使用して銀行口座を確認します。 前のステップで行った `confirmSetupIntent` メソッドの呼び出しの結果として、`requires_action` 状態の SetupIntent が返されます。SetupIntent には、確認を完了するための有益な情報を含む [next_action](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-next_action-verify_with_microdeposits) フィールドが含まれています。 [請求書メール](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-billing_details-email)を指定した場合、Stripe はこのメールで入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了することができます。 > 確認の失敗は、明細書表記ベースの少額入金の場合は 10 回、金額ベースの少額入金の場合は 3 回までです。この上限を超えると、Stripe は銀行口座を確認できなくなります。また、少額入金の確認は 10 日経過するとタイムアウトになります。この期間内に少額入金を確認できなかった場合、PaymentIntent は新しい支払い方法の詳細を要求する状態に戻ります。少額入金とは何か、どのように使用されるのかを顧客に明確に伝えることで、確認に関する問題を回避できます。 ### オプション: カスタムのメール通知を送信する また、顧客に[カスタムのメール通知](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails)を送信することもできます。カスタムメールを設定した後は、顧客が確認メールに応答する方法を指定する必要があります。以下の方法のうち、いずれか _1 つ_を指定してください。 - Stripe 上のオンライン確認ページを使用します。これを行うには、[next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-verify_with_microdeposits-hosted_verification_url) オブジェクトの `verify_with_microdeposits[hosted_verification_url]` URL を使用し、顧客に確認プロセスを完了するよう指示します。 - Stripe がオンラインで提供する確認ページを使用しない場合には、ご自身のアプリにフォームを作成します。顧客はこのフォームを使用して少額入金の金額を伝え、iOS SDK を使用して銀行口座を確認します。 - 少なくとも `descriptor code` パラメーター (確認のための 6 桁の文字列) を処理するフォームを設定します。 - また Stripe では、`amounts` パラメーターも処理するようにフォームを設定することをお勧めします。これはこのパラメーターが、顧客が利用する一部の銀行で必要とされることがあるためです。 組み込みは、`descriptor_code` 「または」 `amounts` のみを渡します。組み込みでどちらが使用されるかを判断するには、`next_action` オブジェクトの `verify_with_microdeposits[microdeposit_type]` の値を確認します。 #### Swift ```swift // Use if you are using a descriptor code, do not use if you are using amounts STPAPIClient.shared.verifySetupIntentWithMicrodeposits(clientSecret: clientSecret, descriptorCode: descriptorCode, completion: { intent, error in }) // Use if you are using amounts, do not use if you are using descriptor code STPAPIClient.shared.verifySetupIntentWithMicrodeposits(clientSecret: clientSecret, firstAmount: firstAmount, secondAmount: secondAmount, completion: { intent, error in }) ``` 銀行口座の確認が成功すると、Stripe は、`succeeded` の `status` の SetupIntent オブジェクトを返します。 確認が失敗する理由はいくつかあります。失敗は、直接的なエラー応答として同期的に発生します。 ```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" } } ``` | エラーコード | メッセージ | ステータスの変化 | | ------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------ | | `payment_method_microdeposit_failed` | 少額入金に失敗しました。指定した銀行口座、金融機関、支店の番号を確認してください。 | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 | | `payment_method_microdeposit_verification_amounts_mismatch` | 指定された金額が銀行口座に送金された金額と一致しません。確認試行の残り回数はあと {attempts_remaining} 回です。 | 変化なし | | `payment_method_microdeposit_verification_attempts_exceeded` | 許容された確認の試行回数を超えました。 | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 | ## 組み込みをテストする [Financial Connections](https://docs.stripe.com/financial-connections/testing.md#web-how-to-use-test-accounts) を使用して即時確認を行うシナリオをテストする方法をご紹介します。 ### サンドボックスで取引メールを送信する 銀行口座の詳細を収集し、同意書を受け付けたら、*サンドボックス* (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)で同意書の確認メールと少額入金の確認メールを送信します。 ドメインが **{domain}** で、ユーザー名が **{username}** の場合、メール形式 **{username}+test\_email@{domain}** を使用してテスト取引メールを送信します。 たとえば、ドメインが **example.com** でユーザー名が **info** の場合、ACH Direct Debit 決済のテストには **info+test\_email@example.com** という形式を使用します。この形式により、メールが正しくルーティングされます。**+test\_email** サフィックスを含めない場合、メールは送信されません。 > テスト中にこれらのメールをトリガーするには、[Stripe の本番環境利用の申請](https://docs.stripe.com/get-started/account/activate.md)を行う必要があります。 ### テスト用口座番号 Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号と対応するトークンをいくつか用意しています。 | 口座番号 | トークン | 金融番号 | 動作 | | -------------- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `000123456789` | `pm_usBankAccount_success` | `110000000` | 支払いは成功します。 | | `000111111113` | `pm_usBankAccount_accountClosed` | `110000000` | 口座が解約済みであるため、支払いは失敗します。 | | `000000004954` | `pm_usBankAccount_riskLevelHighest` | `110000000` | この支払いは、[不正利用のリスクが高い](https://docs.stripe.com/radar/risk-evaluation.md#high-risk)ため、Radar によってブロックされています。 | | `000111111116` | `pm_usBankAccount_noAccount` | `110000000` | 口座が見つからないため、支払いは失敗します。 | | `000222222227` | `pm_usBankAccount_insufficientFunds` | `110000000` | 残高不足のため、支払いは失敗します。 | | `000333333335` | `pm_usBankAccount_debitNotAuthorized` | `110000000` | 引き落としがオーソリされていないため、支払いは失敗します。 | | `000444444440` | `pm_usBankAccount_invalidCurrency` | `110000000` | 通貨が無効であるため、支払いは失敗します。 | | `000666666661` | `pm_usBankAccount_failMicrodeposits` | `110000000` | 支払いで少額入金の送金が失敗します。 | | `000555555559` | `pm_usBankAccount_dispute` | `110000000` | 支払いによって不審請求の申請が開始されています。 | | `000000000009` | `pm_usBankAccount_processing` | `110000000` | 支払いは無期限に処理中のままになります。 [PaymentIntent キャンセル](https://docs.stripe.com/api/payment_intents/cancel.md) をテストするのに役立ちます。 | | `000777777771` | `pm_usBankAccount_weeklyLimitExceeded` | `110000000` | 支払い額がアカウントの週次支払い額の上限を超えているため、支払いが失敗しました。 | | `000888888885` | | `110000000` | [トークン化されたアカウント番号](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md)が無効化されると決済が失敗します。 | テスト取引を完了する前に、自動的に支払いに成功または失敗するテスト用のすべての口座を確認する必要があります。確認するには、下記の少額入金のテスト用の金額または明細書表記コードを使用します。 ### 少額入金の金額と明細書表記コードをテストする さまざまなシナリオを再現するために、これらの少額入金の金額「または」明細書表記コードの値 0.01 を使用します。 | 少額入金の金額 | 明細書表記コードの値 0.01 | シナリオ | | ------------- | --------------- | ------------------------- | | `32` および `45` | SM11AA | アカウントの確認をシミュレーションします。 | | `10` および `11` | SM33CC | 許容された確認回数の超過をシミュレーションします。 | | `40` および `41` | SM44DD | 少額入金のタイムアウトをシミュレーションします。 | ### 売上処理の動作をテストする テスト取引は即座に売上として処理され、利用可能なテスト残高に追加されます。この動作は、利用可能な残高で取引が売上として処理されるまでに[数日](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#timing)かかることがある、本番環境とは異なります。 ## 将来の決済を受け付ける [サーバー側] SetupIntent が成功すると、新しい *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が作成され [Customer](https://docs.stripe.com/api/customers.md) に関連付けられます。これらは、顧客に銀行口座の入力を再度求めることなく将来の支払いを開始するために使用されます。 #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "amount"=1099 \ -d "currency"="usd" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "payment_method"="{{PAYMENT_METHOD_ID}}" \ -d "payment_method_types[]"="us_bank_account" \ -d "confirm"="true" ``` ## Optional: 即時の確認のみ [サーバー側] デフォルトでは、アメリカの銀行口座による決済手段を設定すると、顧客は銀行口座の即時確認、または少額入金を使用できます。SetupIntent を作成するときに、[verification_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method_options-us_bank_account-verification_method) パラメーターを使用して、銀行口座の即時確認のみを必要に応じて要求することができます。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` これにより、少額入金の確認を処理する必要はなくなりますが、即時確認に失敗した場合は、SetupIntent のステータスは、顧客の銀行口座の即時確認に失敗したことを示す `requires_payment_method` となります。 ## Optional: 少額入金のみによる確認 [サーバー側] デフォルトでは、顧客はアメリカの銀行口座を使用する決済手段を設定することで、銀行口座の即時確認、または少額入金を実行できます。SetupIntent を作成するときに、[verification_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method_options-us_bank_account-verification_method) パラメーターを使用して、少額入金の確認を必要に応じて要求することができます。 > カスタムの決済フォームを使用する場合は、独自の UI を構築して銀行口座情報を収集します。少額入金に関する Stripe からのメールを無効にしている場合は、少額入金のコードまたは金額を確認できるよう、顧客用の UI を構築する必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=microdeposits" ``` 独自の UI で顧客の銀行口座情報を収集した後、その詳細を使用して [STPPaymentHandler.confirmSetupIntent](https://stripe.dev/stripe-ios/stripepayments/documentation/stripepayments/stppaymenthandler/confirmsetupintent\(_:with:completion:\)) を呼び出し、SetupIntent を完了します。 #### Swift ```swift // Use your own UI to collect your customer's input let accountholderName = // … let email = // … let accountNumber = // … let routingNumber = // … let accountType = // … let accountHolderType = // … let usBankAccountParams = STPPaymentMethodUSBankAccountParams() usBankAccountParams.accountNumber = accountNumber usBankAccountParams.routingNumber = routingNumber usBankAccountParams.accountType = accountType usBankAccountParams.accountHolderType = accountHolderType let billingDetails = STPPaymentMethodBillingDetails() billingDetails.name = accountholderName billingDetails.email = email let paymentMethodParams = STPPaymentMethodParams(usBankAccount: usBankAccountParams, billingDetails: billingDetails, metadata: nil) let setupIntentParams = STPSetupIntentConfirmParams(clientSecret: clientSecret) setupIntentParams.paymentMethodParams = paymentMethodParams setupIntentParams.returnURL = "https://your-app-domain.com/stripe-redirect" STPPaymentHandler.shared().confirmSetupIntent( setupIntentParams, with: self ) { (status, intent, error) in // Handle the result } ``` ## Optional: デフォルトの支払い方法を更新する [サーバー側] `SetupIntent` が `succeeded` 状態に達すると、顧客の `default_payment_method` を更新できます。 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' if event.type == 'setup_intent.succeeded' setup_intent = event.data.object customer_id = setup_intent['customer'] payment_method_id = setup_intent['payment_method'] # Set the default payment method Stripe::Customer.update( customer_id, { invoice_settings: { default_payment_method: payment_method_id } } ) end ``` # Android > This is a Android for when payment-ui is mobile and platform is android. View the full page at https://docs.stripe.com/payments/ach-direct-debit/set-up-payment?payment-ui=mobile&platform=android. [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)の無料トライアルを開始する > ACH Direct Debit は、[遅延通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であるため、支払い後に資金はすぐには利用可能になりません。通常、決済金額がアカウントに入金されるまでに 4 営業日かかります。 [Stripe Android SDK](https://github.com/stripe/stripe-android) はオープンソースであり、[詳細なドキュメントが提供されています](https://stripe.dev/stripe-android/)。 SDK をインストールするには、[app/build.gradle](https://developer.android.com/studio/build/dependencies) ファイルの `dependencies` ブロックに `stripe-android` および `financial-connections` を追加します。 #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Stripe Android SDK implementation("com.stripe:stripe-android:23.2.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.2.0") // Financial Connections SDK implementation("com.stripe:financial-connections:23.2.0") } ``` > SDK の最新リリースおよび過去バージョンの詳細については、GitHub の [Releases](https://github.com/stripe/stripe-android/releases) ページをご覧ください。新しいリリースの公開時に通知を受け取るには、[リポジトリのリリースを確認](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository)してください。 Stripe の[公開可能キー](https://dashboard.stripe.com/apikeys)を使用して SDK を設定し、 `Application` サブクラスなどで、Stripe API へのリクエストを実行できるようにします。 #### Kotlin ```kotlin import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "<>" ) } } ``` > テストおよび開発時には[テストキー](https://docs.stripe.com/keys.md#obtain-api-keys)を使用し、アプリの公開時には[本番環境](https://docs.stripe.com/keys.md#test-live-modes)キーを使用します。 ## 顧客を作成または取得する [推奨] [サーバー側] > #### Use the Accounts v2 API to represent customers > > The Accounts v2 API is GA for Connect users, and in public preview for other Stripe users. All Stripe users can enable Accounts v2 [in their Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). However, when making calls to the Accounts v2 API, preview users need to [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定の Account オブジェクトとしてモデル化する](https://docs.stripe.com/connect/use-accounts-as-customers.md)ことをお勧めします。 #### Accounts v2 ユーザーがあなたのビジネスでアカウントを作成したときに、顧客が設定する [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) オブジェクトを作成するか、このユーザーに関連付けられた既存の `Account` を取得します。`Account` オブジェクトの ID を自社の顧客に関する内部表現に関連付けると、後で保存済みの決済手段の詳細を取得して利用できます。`Account` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "contact_email": "{{CUSTOMER_EMAIL}}" }' ``` #### Customers v1 ユーザーがあなたのビジネスでアカウントを作成したときに、*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` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} ``` ## SetupIntent を作成する [サーバー側] [クライアント側] [SetupIntent](https://docs.stripe.com/api/setup_intents.md) は、将来の支払いに備えて顧客の決済手段を設定する意図を示すオブジェクトです。`SetupIntent` は、この設定プロセスの手順を追跡します。 ### サーバー側 [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) を us_bank_account に設定してサーバーで SetupIntent を作成し、Customer の [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) を指定します。 Financial Connections 手数料の詳細については、[料金体系の詳細](https://stripe.com/financial-connections#pricing)をご覧ください。 デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、[Financial Connections](https://docs.stripe.com/financial-connections.md) で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、[Financial Connections に関するドキュメント](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)をご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。 > 顧客がアカウントを認証した後で、追加データにアクセスを拡張するには、権限を拡張してアカウントを再度関連付ける必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` ### クライアント側 返された 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)) が含まれています。これは、SetupIntent オブジェクト全体を渡すことなく安全に設定を完了するために、クライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。 #### Kotlin ```kotlin import androidx.appcompat.app.AppCompatActivity class CheckoutActivity : AppCompatActivity() { lateinit var setupIntentClientSecret: String fun startCheckout() { // Request a SetupIntent from your server and store its client secret } } ``` ## 支払い方法の詳細を収集する [クライアント側] ACH ダイレクトデビットで決済を成功させるには、顧客の氏名と (オプションで) メールアドレスが必要です。アプリで、必要な請求詳細を顧客から収集します。 - 顧客の氏名 (姓と名) - 顧客のメールアドレス `CollectBankAccountConfiguration.USBankAccount` を使用し、`presentWithSetupIntent` を呼び出すために必要なパラメーターを作成します。 決済アクティビティーの onCreate 内で CollectBankAccountLauncher インスタンスを初期化して、結果を処理するためのメソッドを渡します。次に、`presentWithSetupIntent` を呼び出して銀行口座情報を収集し、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) を作成して SetupIntent に関連付けます。 #### Kotlin ```kotlin import androidx.appcompat.app.AppCompatActivity class CheckoutActivity : AppCompatActivity() { private lateinit var setupIntentClientSecret: String private lateinit var collectBankAccountLauncher: CollectBankAccountLauncher override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Create collector collectBankAccountLauncher = CollectBankAccountLauncher.create( this ) { result: CollectBankAccountResult -> when (result) { is CollectBankAccountResult.Completed -> { val intent = result.response.intent if (intent.status === StripeIntent.Status.RequiresPaymentMethod) { // Customer canceled the Financial Connections modal. Present them with other // payment method type options. } else if (intent.status === StripeIntent.Status.RequiresConfirmation) { // We collected an account - possibly instantly verified, but possibly // manually-entered. Display payment method details and mandate text // to the customer and confirm the intent once they accept // the mandate. } } is CollectBankAccountResult.Cancelled -> { // handle cancellation } is CollectBankAccountResult.Failed -> { // handle error print("Error: ${result.error}") } } } } fun startCheckout() { // ... // Build params val collectParams: CollectBankAccountConfiguration = CollectBankAccountConfiguration.USBankAccount( name, email ) // Calling this method will trigger the Financial Connections modal to be displayed collectBankAccountLauncher.presentWithSetupIntent( publishableKey, setupIntentClientSecret, collectParams ) } } ``` これにより、銀行口座の詳細の収集と確認を処理するモーダル UI が読み込まれます。処理が完了すると、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が SetupIntent に自動的に関連付けられます。 ## Optional: Financial Connections 銀行口座のデータにアクセスする [サーバー側] SetupIntentの作成時に、追加の[データ権限](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions)をリクエストする場合にのみ、Financial Connections データにアクセスできます。 顧客が[Stripe Financial Connections 認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を完了すると、返される `us_bank_account` PaymentMethod には、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md)を指す [financial_connections_account](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-us_bank_account-financial_connections_account) ID が含まれます。この ID を使用して口座データにアクセスします。 > 顧客が手動入力および少額入金によって関連付けた銀行口座には、Payment Method の `financial_connections_account` ID がありません。 Financial Connections アカウント ID を特定するには、SetupIntent を取得して `payment_method` 属性を拡張します。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUPINTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` ```json { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", // ... "type": "us_bank_account" "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK","financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", "fingerprint": "q9qchffggRjlX2tb", "last4": "6789", "routing_number": "110000000" } } // ... } ``` 残高データにアクセスできる場合には、収集した支払い方法で支払いを開始する前に[残高を確認する](https://docs.stripe.com/financial-connections/balances.md#initiate-balance-refresh)ことをお勧めします。 追加の口座データを使用して、[Financial Connections](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#optimize) で ACH の実装を最適化する方法をご紹介します。 ## 同意書承認を収集し送信する [クライアント側] SetupIntent を完了して顧客の支払い方法の詳細を保存する前に、同意書の規約を表示して支払いに対する承認を得る必要があります。 *Nacha* (Nacha is the governing body that oversees the ACH network) の運営規則に準拠するため、決済を開始する前に、同意書の規約を表示して顧客から承認を得る必要があります。[同意書](https://docs.stripe.com/payments/ach-direct-debit.md#mandates)の詳細については、こちらの記事をご覧ください。 顧客が同意書の規約を承認する際、Setup を確定する必要があります。顧客がフォームを送信したら、`confirm` を使用して決済を完了します。 #### Kotlin ```kotlin class CheckoutActivity : AppCompatActivity() { // ... private lateinit var setupIntentClientSecret: String private val paymentLauncher: PaymentLauncher by lazy { val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext) PaymentLauncher.Companion.create( this, paymentConfiguration.publishableKey, paymentConfiguration.stripeAccountId, ::onPaymentResult ) } private fun startCheckout() { // ... val confirmParams = ConfirmSetupIntentParams.create( clientSecret = setupIntentClientSecret, paymentMethodType = PaymentMethod.Type.USBankAccount ) paymentLauncher.confirm(confirmParams) } private fun onPaymentResult(paymentResult: PaymentResult) { when (paymentResult) { is PaymentResult.Completed -> { // show success UI } is PaymentResult.Canceled -> { // handle cancel flow } is PaymentResult.Failed -> { // handle failures // (for example, the customer might need to choose a new payment // method) } } } } ``` > `confirm` が完了するまでには数秒かかる場合があります。この間、フォームが再送信されないように無効化し、待機中のインジケーター (スピナーなど) を表示します。エラーが発生した場合には顧客に表示して、フォームを再度有効化し、待機中のインジケーターを非表示にします。 成功した場合、Stripe から以下のいずれかのステータスで SetupIntent オブジェクトが返されます。 | ステータス | 説明 | 次のステップ | | ----------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `succeeded` | 銀行口座が即座に確認されたか、確認が必要ありませんでした。 | アクションは不要です | | `requires_action` | 銀行口座の確認を完了するには、追加のアクションが必要です。 | ステップ 6: [少額入金で銀行口座を確認する](https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment.md#android-verify-with-microdeposits) | Setup の確定に成功した後、同意書の確認メールと収集した銀行口座情報を顧客に送信する必要があります。Stripe はデフォルトでこれらの処理を行いますが、ご希望に応じて[カスタム通知の送信](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails)を選択することもできます。 ## 少額入金で銀行口座を確認する [クライアント側] すべての顧客が銀行口座を即時に確認できるわけではありません。このステップは、顧客が前のステップで即時確認フローからオプトアウトした場合にのみ適用されます。 このような場合、Stripe は `descriptor_code` による少額入金を送金し、銀行口座の確認でさらに問題が発生した場合には、`amount` による少額入金に戻る場合があります。これらの入金が顧客のオンライン明細書に表示されるには 1 ～ 2 営業日かかります。 - **明細書表記コード**。Stripe は、SM で始まる一意の 6 桁の `descriptor_code` を使用し、0.01 USD の 1 件の少額入金を顧客の銀行口座に送金します。顧客は、この文字列を使用して銀行口座を確認します。 - **金額**。Stripe は、`ACCTVERIFY` という明細書表記を使用し、一意でない 2 件の少額入金を顧客の銀行口座に送金します。顧客は、この入金額を使用して銀行口座を確認します。 前のステップで行った `confirmSetupIntent` メソッドの呼び出しの結果として、`requires_action` 状態の SetupIntent が返されます。SetupIntent には、確認を完了するための有益な情報を含む [next_action](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-next_action-verify_with_microdeposits) フィールドが含まれています。 [請求書メール](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-billing_details-email)を指定した場合、Stripe はこのメールで入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了することができます。 > 確認の失敗は、明細書表記ベースの少額入金の場合は 10 回、金額ベースの少額入金の場合は 3 回までです。この上限を超えると、Stripe は銀行口座を確認できなくなります。また、少額入金の確認は 10 日経過するとタイムアウトになります。この期間内に少額入金を確認できなかった場合、PaymentIntent は新しい支払い方法の詳細を要求する状態に戻ります。少額入金とは何か、どのように使用されるのかを顧客に明確に伝えることで、確認に関する問題を回避できます。 ### オプション: カスタムのメール通知を送信する また、顧客に[カスタムのメール通知](https://docs.stripe.com/payments/ach-direct-debit.md#mandate-and-microdeposit-emails)を送信することもできます。カスタムメールを設定した後は、顧客が確認メールに応答する方法を指定する必要があります。以下の方法のうち、いずれか _1 つ_を指定してください。 - Stripe 上のオンライン確認ページを使用します。これを行うには、[next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-verify_with_microdeposits-hosted_verification_url) オブジェクトの `verify_with_microdeposits[hosted_verification_url]` URL を使用し、顧客に確認プロセスを完了するよう指示します。 - Stripe がオンラインで提供する確認ページを使用しない場合には、ご自身のアプリにフォームを作成します。顧客はこのフォームを使用して少額入金の金額を伝え、Android SDK を使用して銀行口座を確認します。 - 少なくとも `descriptor code` パラメーター (確認のための 6 桁の文字列) を処理するフォームを設定します。 - また Stripe では、`amounts` パラメーターも処理するようにフォームを設定することをお勧めします。これはこのパラメーターが、顧客が利用する一部の銀行で必要とされることがあるためです。 組み込みは、`descriptor_code` *「または」* `amounts` のみを渡します。組み込みでどちらが使用されるかを判断するには、`next_action` オブジェクトの `verify_with_microdeposits[microdeposit_type]` の値を確認します。 #### Kotlin ```kotlin // Use if you are using a descriptor code, do not use if you are using amounts fun verifySetupIntentWithMicrodeposits( clientSecret: String, descriptorCode: String, callback: ApiResultCallback ) // Use if you are using amounts, do not use if you are using descriptor code fun verifySetupIntentWithMicrodeposits( clientSecret: String, firstAmount: Int, secondAmount: Int, callback: ApiResultCallback ) ``` 銀行口座の確認が成功すると、Stripe は、`succeeded` の `status` の SetupIntent オブジェクトを返します。 確認が失敗する理由はいくつかあります。失敗は、直接的なエラー応答として同期的に発生します。 ```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" } } ``` | エラーコード | メッセージ | ステータスの変化 | | ------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------ | | `payment_method_microdeposit_failed` | 少額入金に失敗しました。指定した銀行口座、金融機関、支店の番号を確認してください。 | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 | | `payment_method_microdeposit_verification_amounts_mismatch` | 指定された金額が銀行口座に送金された金額と一致しません。確認試行の残り回数はあと {attempts_remaining} 回です。 | 変化なし | | `payment_method_microdeposit_verification_attempts_exceeded` | 許容された確認の試行回数を超えました。 | `status` は `requires_payment_method` で、`last_setup_error` が設定されます。 | ## 組み込みをテストする [Financial Connections](https://docs.stripe.com/financial-connections/testing.md#web-how-to-use-test-accounts) を使用して即時確認を行うシナリオをテストする方法をご紹介します。 ### サンドボックスで取引メールを送信する 銀行口座の詳細を収集し、同意書を受け付けたら、*サンドボックス* (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)で同意書の確認メールと少額入金の確認メールを送信します。 ドメインが **{domain}** で、ユーザー名が **{username}** の場合、メール形式 **{username}+test\_email@{domain}** を使用してテスト取引メールを送信します。 たとえば、ドメインが **example.com** でユーザー名が **info** の場合、ACH Direct Debit 決済のテストには **info+test\_email@example.com** という形式を使用します。この形式により、メールが正しくルーティングされます。**+test\_email** サフィックスを含めない場合、メールは送信されません。 > テスト中にこれらのメールをトリガーするには、[Stripe の本番環境利用の申請](https://docs.stripe.com/get-started/account/activate.md)を行う必要があります。 ### テスト用口座番号 Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号と対応するトークンをいくつか用意しています。 | 口座番号 | トークン | 金融番号 | 動作 | | -------------- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `000123456789` | `pm_usBankAccount_success` | `110000000` | 支払いは成功します。 | | `000111111113` | `pm_usBankAccount_accountClosed` | `110000000` | 口座が解約済みであるため、支払いは失敗します。 | | `000000004954` | `pm_usBankAccount_riskLevelHighest` | `110000000` | この支払いは、[不正利用のリスクが高い](https://docs.stripe.com/radar/risk-evaluation.md#high-risk)ため、Radar によってブロックされています。 | | `000111111116` | `pm_usBankAccount_noAccount` | `110000000` | 口座が見つからないため、支払いは失敗します。 | | `000222222227` | `pm_usBankAccount_insufficientFunds` | `110000000` | 残高不足のため、支払いは失敗します。 | | `000333333335` | `pm_usBankAccount_debitNotAuthorized` | `110000000` | 引き落としがオーソリされていないため、支払いは失敗します。 | | `000444444440` | `pm_usBankAccount_invalidCurrency` | `110000000` | 通貨が無効であるため、支払いは失敗します。 | | `000666666661` | `pm_usBankAccount_failMicrodeposits` | `110000000` | 支払いで少額入金の送金が失敗します。 | | `000555555559` | `pm_usBankAccount_dispute` | `110000000` | 支払いによって不審請求の申請が開始されています。 | | `000000000009` | `pm_usBankAccount_processing` | `110000000` | 支払いは無期限に処理中のままになります。 [PaymentIntent キャンセル](https://docs.stripe.com/api/payment_intents/cancel.md) をテストするのに役立ちます。 | | `000777777771` | `pm_usBankAccount_weeklyLimitExceeded` | `110000000` | 支払い額がアカウントの週次支払い額の上限を超えているため、支払いが失敗しました。 | | `000888888885` | | `110000000` | [トークン化されたアカウント番号](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md)が無効化されると決済が失敗します。 | テスト取引を完了する前に、自動的に支払いに成功または失敗するテスト用のすべての口座を確認する必要があります。確認するには、下記の少額入金のテスト用の金額または明細書表記コードを使用します。 ### 少額入金の金額と明細書表記コードをテストする さまざまなシナリオを再現するために、これらの少額入金の金額「または」明細書表記コードの値 0.01 を使用します。 | 少額入金の金額 | 明細書表記コードの値 0.01 | シナリオ | | ------------- | --------------- | ------------------------- | | `32` および `45` | SM11AA | アカウントの確認をシミュレーションします。 | | `10` および `11` | SM33CC | 許容された確認回数の超過をシミュレーションします。 | | `40` および `41` | SM44DD | 少額入金のタイムアウトをシミュレーションします。 | ### 売上処理の動作をテストする テスト取引は即座に売上として処理され、利用可能なテスト残高に追加されます。この動作は、利用可能な残高で取引が売上として処理されるまでに[数日](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#timing)かかることがある、本番環境とは異なります。 ## 将来の決済を受け付ける [サーバー側] SetupIntent が成功すると、新しい *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が作成され [Customer](https://docs.stripe.com/api/customers.md) に関連付けられます。これらは、顧客に銀行口座の入力を再度求めることなく将来の支払いを開始するために使用されます。 #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "amount"=1099 \ -d "currency"="usd" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "payment_method"="{{PAYMENT_METHOD_ID}}" \ -d "payment_method_types[]"="us_bank_account" \ -d "confirm"="true" ``` ## Optional: 即時の確認のみ [サーバー側] デフォルトでは、アメリカの銀行口座による決済手段を設定すると、顧客は銀行口座の即時確認、または少額入金を使用できます。SetupIntent を作成するときに、[verification_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method_options-us_bank_account-verification_method) パラメーターを使用して、銀行口座の即時確認のみを必要に応じて要求することができます。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` これにより、少額入金の確認を処理する必要はなくなりますが、即時確認に失敗した場合は、SetupIntent のステータスは、顧客の銀行口座の即時確認に失敗したことを示す `requires_payment_method` となります。 ## Optional: 少額入金のみによる確認 [サーバー側] デフォルトでは、顧客はアメリカの銀行口座を使用する決済手段を設定することで、銀行口座の即時確認、または少額入金を実行できます。SetupIntent を作成するときに、[verification_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method_options-us_bank_account-verification_method) パラメーターを使用して、少額入金の確認を必要に応じて要求することができます。 > カスタムの決済フォームを使用する場合は、独自の UI を構築して銀行口座情報を収集します。少額入金に関する Stripe からのメールを無効にしている場合は、少額入金のコードまたは金額を確認できるよう、顧客用の UI を構築する必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=microdeposits" ``` 独自の UI で顧客の銀行口座情報を収集した後、その詳細を使用して [PaymentLauncher.confirm](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-launcher/confirm.html) を呼び出し、SetupIntent を完了します。 #### Kotlin ```kotlin class CheckoutActivity : AppCompatActivity() { private lateinit var setupIntentClientSecret: String private val paymentLauncher: PaymentLauncher = // … private fun confirmSetupIntent() { // Use your own UI to collect your customer's input val accountholderName: String = // … val email: String = // … val accountNumber: String = // … val routingNumber: String = // … val accountType: PaymentMethod.USBankAccount.USBankAccountType = // … val accountHolderType: PaymentMethod.USBankAccount.USBankAccountHolderType = // … val createParams = PaymentMethodCreateParams.create( usBankAccount = PaymentMethodCreateParams.USBankAccount( accountNumber = accountNumber, routingNumber = routingNumber, accountType = accountType, accountHolderType = accountHolderType, ), billingDetails = PaymentMethod.BillingDetails( name = accountholderName, email = email, ), ) val confirmParams = ConfirmSetupIntentParams.create( paymentMethodCreateParams = createParams, clientSecret = setupIntentClientSecret, ) paymentLauncher.confirm(confirmParams) } } ``` ## Optional: デフォルトの支払い方法を更新する [サーバー側] `SetupIntent` が `succeeded` 状態に達すると、顧客の `default_payment_method` を更新できます。 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' if event.type == 'setup_intent.succeeded' setup_intent = event.data.object customer_id = setup_intent['customer'] payment_method_id = setup_intent['payment_method'] # Set the default payment method Stripe::Customer.update( customer_id, { invoice_settings: { default_payment_method: payment_method_id } } ) end ``` # React Native > This is a React Native for when payment-ui is mobile and platform is react-native. View the full page at https://docs.stripe.com/payments/ach-direct-debit/set-up-payment?payment-ui=mobile&platform=react-native. [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)の無料トライアルを開始する > ACH Direct Debit は、[遅延通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であるため、支払い後に資金はすぐには利用可能になりません。通常、決済金額がアカウントに入金されるまでに 4 営業日かかります。 ## Stripe を設定する [サーバ側] [クライアント側] ### サーバ側 この組み込みには、Stripe API と通信するエンドポイントがサーバ上に必要です。Stripe の公式ライブラリを使用して、サーバから 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' ``` ### クライアント側 [React Native SDK](https://github.com/stripe/stripe-react-native) はオープンソースであり、詳細なドキュメントが提供されています。内部では、[ネイティブの iOS](https://github.com/stripe/stripe-ios) および [Android](https://github.com/stripe/stripe-android) の SDK を使用します。Stripe の React Native SDK をインストールするには、プロジェクトのディレクトリーで (使用するパッケージマネージャーによって異なる) 次のいずれかのコマンドを実行します。 #### yarn ```bash yarn add @stripe/stripe-react-native ``` #### npm ```bash npm install @stripe/stripe-react-native ``` 次に、その他の必要な依存関係をインストールします。 - iOS の場合は、**ios** ディレクトリに移動して `pod install` を実行し、必要なネイティブ依存関係もインストールします。 - Android の場合は、依存関係をインストールする必要はありません。 > [公式の TypeScript ガイド](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project)に従って TypeScript のサポートを追加することをお勧めします。 ### Stripe の初期化 React Native アプリで Stripe を初期化するには、決済画面を `StripeProvider` コンポーネントでラップするか、`initStripe` 初期化メソッドを使用します。`publishableKey` の API [公開可能キー](https://docs.stripe.com/keys.md#obtain-api-keys)のみが必要です。次の例は、`StripeProvider` コンポーネントを使用して Stripe を初期化する方法を示しています。 ```jsx import { useState, useEffect } from 'react'; import { StripeProvider } from '@stripe/stripe-react-native'; function App() { const [publishableKey, setPublishableKey] = useState(''); const fetchPublishableKey = async () => { const key = await fetchKey(); // fetch key from your server here setPublishableKey(key); }; useEffect(() => { fetchPublishableKey(); }, []); return ( {/* Your app code here */} ); } ``` > テストおよび開発時には API の[テストキー](https://docs.stripe.com/keys.md#obtain-api-keys)を使用し、アプリの公開時には[本番環境](https://docs.stripe.com/keys.md#test-live-modes)キーを使用します。 ## 顧客を作成または取得する [推奨] [サーバー側] > #### Use the Accounts v2 API to represent customers > > The Accounts v2 API is GA for Connect users, and in public preview for other Stripe users. All Stripe users can enable Accounts v2 [in their Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup). However, when making calls to the Accounts v2 API, preview users need to [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定の Account オブジェクトとしてモデル化する](https://docs.stripe.com/connect/use-accounts-as-customers.md)ことをお勧めします。 #### Accounts v2 ユーザーがあなたのビジネスでアカウントを作成したときに、顧客が設定する [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) オブジェクトを作成するか、このユーザーに関連付けられた既存の `Account` を取得します。`Account` オブジェクトの ID を自社の顧客に関する内部表現に関連付けると、後で保存済みの決済手段の詳細を取得して利用できます。`Account` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "contact_email": "{{CUSTOMER_EMAIL}}" }' ``` #### Customers v1 ユーザーがあなたのビジネスでアカウントを作成したときに、*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` にメールアドレスを含めると、Financial Connections の [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization) を有効にできます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} ``` ## SetupIntent を作成する [サーバー側] [SetupIntent](https://docs.stripe.com/api/setup_intents.md) は、将来の支払いに備えて顧客の決済手段を設定する意図を示すオブジェクトです。`SetupIntent` は、この設定プロセスの手順を追跡します。 [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) を `us_bank_account` に設定してサーバーで SetupIntent を作成し、Customer の [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) を指定します。 ### サーバー側 [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) を `us_bank_account` に設定してサーバーで SetupIntent を作成し、Customer の [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) を指定します。 Financial Connections 手数料の詳細については、[料金体系の詳細](https://stripe.com/financial-connections#pricing)をご覧ください。 デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、[Financial Connections](https://docs.stripe.com/financial-connections.md) で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、[Financial Connections に関するドキュメント](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)をご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。 > 顧客がアカウントを認証した後で、追加データにアクセスを拡張するには、権限を拡張してアカウントを再度関連付ける必要があります。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" ``` ### クライアント側 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)) が含まれています。これを React Native アプリで使用することで、SetupIntent オブジェクト全体を渡すことなく安全に支払いプロセスを完了できます。アプリで、サーバーの SetupIntent をリクエストし、その client secret を保存します。 ```javascript function PaymentScreen() { // ... const fetchIntentClientSecret = async () => { const response = await fetch(`${API_URL}/create-intent`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ // This is an example request body, the parameters you pass are up to you customer: '', }), }); const {clientSecret} = await response.json(); return clientSecret; }; return ...; } ``` ## 支払い方法の詳細を収集する [クライアント側] 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)) を使用します。これは、Stripe API リクエストを認証する API キーとは異なります。 client secret は支払いを確定できるため、慎重に取り扱う必要があります。記録したり、URL に埋め込んだり、当該の顧客以外に漏洩することがないようにしてください。 [collectBankAccountForSetup](https://docs.stripe.com/js/setup_intents/collect_bank_account_for_setup) を使用して銀行口座の詳細を収集し、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) を作成して SetupIntent に関連付けます。ACH Direct Debit PaymentMethod を作成するには、`billingDetails` パラメーターに口座名義人を含める必要があります。 ```javascript import {collectBankAccountForSetup} from '@stripe/stripe-react-native'; export default function MyPaymentScreen() { const [name, setName] = useState(''); const handleCollectBankAccountPress = async () => { // Fetch the intent client secret from the backend. // See `fetchIntentClientSecret()`'s implementation above. const {clientSecret} = await fetchIntentClientSecret(); const {setupIntent, error} = await collectBankAccountForSetup( clientSecret, { paymentMethodType: 'USBankAccount', paymentMethodData: { billingDetails: { name: "John Doe", }, }, }, ); if (error) { Alert.alert(`Error code: ${error.code}`, error.message); } else if (setupIntent) { Alert.alert('Setup status:', setupIntent.status); if (setupIntent.status === SetupIntents.Status.RequiresConfirmation) { // The next step is to call `confirmSetup` } else if (setupIntent.status === SetupIntents.Status.RequiresAction) { // The next step is to call `verifyMicrodepositsForSetup` } } }; return ( setName(value.nativeEvent.text)} />