ACH ダイレクトデビットによる将来の支払いに備えて詳細を保存する
将来の ACH ダイレクトデビットによる支払いに備えて支払い方法の詳細を保存する方法を紹介します。
You can use the Setup Intents API to collect payment method details in advance, with the final amount or payment date determined later. This is useful for:
- Saving payment methods to a wallet to streamline future purchases
- Collecting surcharges after fulfilling a service
- Starting a free trial for a subscription
注
ACH Direct Debit is a delayed notification payment method, which means that funds aren’t immediately available after payment. A payment typically takes 4 business days to arrive in your account.
Stripe を設定するサーバ側クライアント側
サーバ側
この組み込みには、Stripe API と通信するエンドポイントがサーバ上に必要です。Stripe の公式ライブラリを使用して、サーバから Stripe API にアクセスします。
クライアント側
React Native SDK はオープンソースであり、詳細なドキュメントが提供されています。内部では、ネイティブの iOS および Android の SDK を使用します。Stripe の React Native SDK をインストールするには、プロジェクトのディレクトリーで (使用するパッケージマネージャーによって異なる) 次のいずれかのコマンドを実行します。
次に、その他の必要な依存関係をインストールします。
- iOS の場合は、ios ディレクトリーに移動して
pod install
を実行し、必要なネイティブ依存関係もインストールします。 - Android の場合は、依存関係をインストールする必要はありません。
Stripe の初期化
React Native アプリで Stripe を初期化するには、決済画面を StripeProvider
コンポーネントでラップするか、initStripe
初期化メソッドを使用します。publishableKey
の API 公開可能キーのみが必要です。次の例は、StripeProvider
コンポーネントを使用して Stripe を初期化する方法を示しています。
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 ( <StripeProvider publishableKey={publishableKey} merchantIdentifier="merchant.identifier" // required for Apple Pay urlScheme="your-url-scheme" // required for 3D Secure and bank redirects > // Your app code here </StripeProvider> ); }
顧客を作成または取得する推奨サーバー側
ユーザーがビジネスでアカウントを作成する際に、Customer オブジェクトを作成するか、このユーザーに関連付けられた既存の Customer を取得します。この Customer オブジェクトの ID を、顧客を表す社内の内部表記と関連付けることで、保存されている支払い方法の詳細を後で取得して使用することができます。Financial Connections のリピートユーザーの最適化を有効にするには、Customer にメールアドレスを含めます。
SetupIntent を作成するサーバー側
A SetupIntent is an object that represents your intent to set up a customer’s payment method for future payments. The SetupIntent
tracks the steps of this set-up process.
Create a SetupIntent on your server with payment_method_types set to us_
and specify the Customer’s id.
サーバー側
Create a SetupIntent on your server with payment_method_types set to us_
and specify the Customer’s id.
デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、Financial Connections で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、Financial Connections に関するドキュメントをご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。
注
顧客がアカウントを認証した後で、追加データにアクセスを拡張するには、権限を拡張してアカウントを再度関連付ける必要があります。
クライアント側
SetupIntent には client secret が含まれています。これを React Native アプリで使用することで、SetupIntent オブジェクト全体を渡すことなく安全に支払いプロセスを完了できます。アプリで、サーバーの SetupIntent をリクエストし、その client secret を保存します。
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: '<CUSTOMER_ID>', }), }); const {clientSecret} = await response.json(); return clientSecret; }; return <View>...</View>; }
支払い方法の詳細を収集するクライアント側
SetupIntent オブジェクト全体をクライアントに送信する代わりに、前のステップからの client secret を使用します。これは、Stripe API リクエストを認証する API キーとは異なります。
client secret は支払いを確定できるため、慎重に取り扱う必要があります。記録したり、URL に埋め込んだり、当該の顧客以外に漏洩することがないようにしてください。
Use collectBankAccountForSetup to collect bank account details, create a PaymentMethod, and attach that PaymentMethod to the SetupIntent. You must include the account holder’s name in the billingDetails
parameter to create an ACH Direct Debit PaymentMethod.
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', payment_method_data: { billing_details: { 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 ( <PaymentScreen> <TextInput placeholder="Name" onChange={(value) => setName(value.nativeEvent.text)} /> <Button onPress={handleCollectBankAccountPress} title="Collect bank account" /> </PaymentScreen> ); }
これにより、銀行口座の詳細の収集と確認を処理するモーダル UI が読み込まれます。処理が完了すると、PaymentMethod が SetupIntent に自動的に関連付けられます。
戻り先 URL を設定する (iOS のみ)クライアント側
顧客が Safari や銀行アプリで認証するなどしてアプリを終了した際に、後で自動的にアプリに戻るための方法を提供します。多くの支払い方法タイプでは戻り先 URL が必須であるため、貴社で支払い方法を有効にしていても、URL を指定していない場合、Stripe ではユーザーにその支払い方法を提示することはできません。
To provide a return URL:
- Register a custom URL. Universal links aren’t supported.
- Configure your custom URL.
- Set up your root component to forward the URL to the Stripe SDK as shown below.
注
Expo を使用している場合は、app.
ファイルでスキームを設定します。
import React, { useEffect, useCallback } from 'react'; import { Linking } from 'react-native'; import { useStripe } from '@stripe/stripe-react-native'; export default function MyApp() { const { handleURLCallback } = useStripe(); const handleDeepLink = useCallback( async (url: string | null) => { if (url) { const stripeHandled = await handleURLCallback(url); if (stripeHandled) { // This was a Stripe URL - you can return or add extra handling here as you see fit } else { // This was NOT a Stripe URL – handle as you normally would } } }, [handleURLCallback] ); useEffect(() => { const getUrlAsync = async () => { const initialUrl = await Linking.getInitialURL(); handleDeepLink(initialUrl); }; getUrlAsync(); const deepLinkListener = Linking.addEventListener( 'url', (event: { url: string }) => { handleDeepLink(event.url); } ); return () => deepLinkListener.remove(); }, [handleDeepLink]); return ( <View> <AwesomeAppComponent /> </View> ); }
同意書承認を収集し送信するクライアント側
SetupIntent を完了して顧客の支払い方法の詳細を保存する前に、同意書の規約を表示して顧客から承認を得る必要があります。
To comply with Nacha rules, you must obtain authorization from your customer before you can initiate payment by displaying mandate terms for them to accept. For more information on mandates, see Mandates.
顧客が同意書の規約を承認する際に、お客様は SetupIntent を確定する必要があります。confirmSetup
を使用して、インテントを確定します。
import {confirmSetup} from '@stripe/stripe-react-native'; export default function MyPaymentScreen() { const [name, setName] = useState(''); const handleCollectBankAccountPress = async () => { // See above }; const handlePayPress = async () => { // use the same clientSecret as earlier, see above const {error, setupIntent} = await confirmSetup(clientSecret, { type: 'USBankAccount', }); if (error) { Alert.alert(`Error code: ${error.code}`, error.message); } else if (setupIntent) { if (setupIntent.status === SetupIntents.Status.Processing) { // The debit has been successfully submitted and is now processing } else if ( setupIntent.status === SetupIntents.Status.RequiresAction && setupIntent?.nextAction?.type === 'verifyWithMicrodeposits' ) { // The payment must be verified with `verifyMicrodepositsForPayment` } else { Alert.alert('Payment status:', setupIntent.status); } } }; return ( <PaymentScreen> <TextInput placeholder="Name" onChange={(value) => setName(value.nativeEvent.text)} /> <Button onPress={handleCollectBankAccountPress} title="Collect bank account" /> <Button onPress={handlePayPress} title="Pay" /> </PaymentScreen> ); }
成功した場合、Stripe から以下のいずれかのステータスで SetupIntent オブジェクトが返されます。
ステータス | 説明 | 次のステップ |
---|---|---|
Succeeded | 銀行口座が即座に確認されたか、確認が必要ありませんでした。 | アクションは不要です |
RequiresAction | 銀行口座を確認するには、さらにアクションを実行する必要があります。 | Step 6: Verifying bank accounts with microdeposits |
After successfully confirming the SetupIntent, an email confirmation of the mandate and collected bank account details must be sent to your customer. Stripe handles these by default, but you can choose to send custom notifications if you prefer.
少額入金で銀行口座を確認するクライアント側
すべての顧客が銀行口座を即座に確認できるとは限りません。このような場合、Stripe は少額入金を銀行口座に送金します。この入金は、1 ~ 2 営業日後に顧客のオンライン明細書に表示されます。入金は以下の 2 つのいずれかの形式で行われます。
- 明細書表記コード。Stripe は、SM で始まる一意の 6 桁の
descriptorCode
を使用し、0.01 USD の 1 件の少額入金を顧客の銀行口座に送金します。顧客は、この文字列を使用して銀行口座を確認します。 - 金額。Stripe は、
ACCTVERIFY
という明細書表記を使用し、一意でない 2 件の少額入金を顧客の銀行口座に送金します。顧客は、この入金額を使用して銀行口座を確認します。
前のステップで行った confirmSetup
メソッドの呼び出しの結果として、requiresAction
ステータスの SetupIntent が返される場合、SetupIntent には、確認を完了するための有益な情報を含む next_
フィールドが含まれています。
nextAction: { type: 'verifyWithMicrodeposits'; redirectUrl: "https://payments.stripe.com/…", microdepositType: "descriptor_code"; arrivalDate: "1647586800"; }
請求書メールを指定した場合、Stripe はこのメールで入金の到着予定日を顧客に通知します。このメールには、Stripe がオンラインで提供する確認ページへのリンクが含まれ、顧客はそのページで入金額を確認して銀行口座の確認を完了させることができます。
警告
確認の失敗は、明細書表記ベースの少額入金の場合は 10 回、金額ベースの少額入金の場合は 3 回までです。この上限を超えると、Stripe は銀行口座を確認できなくなります。また、少額入金の確認は 10 日経過するとタイムアウトになります。この期間内に少額入金を確認できなかった場合、PaymentIntent は新しい支払い方法の詳細を要求する状態に戻ります。少額入金とは何か、どのように使用されるのかを顧客に明確に伝えることで、確認に関する問題を回避できます。
支払いが requiresAction
状態であり、nextAction
のタイプが verifyWithMicrodeposits
であることを確認できる場合は、2 つの方法で銀行口座の確認を完了できます。
- 明細書表記コードまたは金額を収集した後、
verifyMicrodepositsForSetup
を呼び出して、入金をアプリで直接確認します。
import { verifyMicrodepositsForSetup } from '@stripe/stripe-react-native'; export default function MyPaymentScreen() { const [verificationText, setVerificationText] = useState(''); return ( <TextInput placeholder="Descriptor code or comma-separated amounts" onChange={(value) => setVerificationText(value.nativeEvent.text)} // Validate and store your user's verification input /> <Button title="Verify microdeposit" onPress={async () => { const { paymentIntent, error } = await verifyMicrodepositsForSetup(secret, { // Provide either the descriptorCode OR amounts, not both descriptorCode: verificationText, amounts: verificationText, }); if (error) { Alert.alert(`Error code: ${error.code}`, error.message); } else if (paymentIntent) { Alert.alert('Payment status:', paymentIntent.status); } }} /> ); }
- Stripe が自動的にオンラインで提供する確認ページを使用します。そのためには、
nextAction
オブジェクトのnextAction[redirectUrl]
URL (上記を参照) を使用し、顧客に確認プロセスを完了するよう指示します。
const {error, setupIntent} = await confirmSetup(clientSecret, { type: 'USBankAccount', }); if (error) { Alert.alert(`Error code: ${error.code}`, error.message); } else if (setupIntent) { if ( setupIntent.status === SetupIntents.Status.RequiresAction && setupIntent?.nextAction?.type === 'verifyWithMicrodeposits' ) { // Open the Stripe-hosted verification page Linking.openURL(setupIntent.nextAction.redirectUrl); } else { Alert.alert('Payment status:', setupIntent.status); } }
銀行口座の確認に成功すると、Stripe は SetupIntent オブジェクトを Succeeded
の status
で返し、setup_intent.succeeded Webhook イベントを送信します。
確認が失敗する原因はいくつか存在します。失敗は直接的なエラー応答として同期的に発生することも、setup_intent.setup_failed Webhook イベントを通じて非同期で発生することもあります (以下の例を参照してください)。
エラーコード | 同期または非同期 | メッセージ | ステータスの変化 |
---|---|---|---|
payment_ | 同期、または Webhook イベントを通じて非同期で発生 | 少額入金に失敗しました。指定した銀行口座、金融機関、支店の番号を確認してください | status は requires_ で、last_ が設定されます。 |
payment_ | 同期 | 指定された金額が銀行口座に送金された金額と一致しません。確認試行の残り回数はあと {attempts_remaining} 回です。 | 変化なし |
payment_ | 同期、または Webhook イベントを通じて非同期で発生 | 許容された確認の試行回数を超えました | status は requires_ で、last_ が設定されます。 |
payment_ | Webhook イベントを通じて非同期で発生 | 少額入金がタイムアウトになりました。顧客は要求された 10 日の期間内に銀行口座を確認しませんでした。 | status は requires_ で、last_ が設定されます。 |
組み込みをテストする
Financial Connections を使用して即時確認を行うシナリオをテストする方法をご紹介します。
テスト環境で取引に関するメールを送信する
銀行口座の詳細を収集し、同意書を受け付けたら、テスト環境で同意書の確認メールと少額入金の確認メールを送信します。これを実行するには、支払い方法の詳細を収集するときに、payment_
フィールドに {any-prefix}+test_
の形式でメールアドレスを指定します。
よくある間違い
テスト環境でこれらのメールをトリガーするには、Stripe の本番環境利用の申請を行う必要があります。
テスト用口座番号
Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号と対応するトークンをいくつか用意しています。
口座番号 | トークン | 金融番号 | 動作 |
---|---|---|---|
000123456789 | pm_ | 110000000 | 支払いは成功します。 |
000111111113 | pm_ | 110000000 | 口座が解約済みであるため、支払いは失敗します。 |
000111111116 | pm_ | 110000000 | 口座が見つからないため、支払いは失敗します。 |
000222222227 | pm_ | 110000000 | 残高不足のため、支払いは失敗します。 |
000333333335 | pm_ | 110000000 | 引き落としがオーソリされていないため、支払いは失敗します。 |
000444444440 | pm_ | 110000000 | 通貨が無効であるため、支払いは失敗します。 |
000666666661 | pm_ | 110000000 | 支払いで少額入金の送金が失敗します。 |
000555555559 | pm_ | 110000000 | 支払いによって不審請求の申請が開始されています。 |
000000000009 | pm_ | 110000000 | 支払いは無期限に処理中のままになります。これは PaymentIntent のキャンセルをテストするのに便利です。 |
000777777771 | pm_ | 110000000 | The payment fails due to payment amount causing the account to exceed its weekly payment volume limit. |
テスト取引を完了する前に、自動的に支払いに成功または失敗するテスト用のすべての口座を確認する必要があります。確認するには、下記の少額入金のテスト用の金額または明細書表記コードを使用します。
少額入金の金額と明細書表記コードをテストする
さまざまなシナリオを再現するために、これらの少額入金の金額「または」明細書表記コードの値 0.01 を使用します。
少額入金の金額 | 明細書表記コードの値 0.01 | シナリオ |
---|---|---|
32 および 45 | SM11AA | アカウントの確認をシミュレーションします。 |
10 および 11 | SM33CC | 許容された確認回数の超過をシミュレーションします。 |
40 および 41 | SM44DD | 少額入金のタイムアウトをシミュレーションします。 |
将来の決済を受け付けるサーバー側
When the SetupIntent succeeds, it creates a new PaymentMethod attached to a Customer. You can use these to initiate future payments without having to prompt the customer for their bank account a second time.