ACH ダイレクトデビットによる支払いを受け付ける

ユーザーがビジネスでアカウントを作成する際に、Customer オブジェクトを作成するか、このユーザーに関連付けられた既存の Customer を取得します。この Customer オブジェクトの ID を、顧客を表す社内の内部表記と関連付けることで、保存されている支払い方法の詳細を後で取得して使用することができます。Financial Connections のリピートユーザーの最適化を有効にするには、Customer にメールアドレスを含めます。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}}

PaymentIntent (支払いインテント) は、顧客から支払いを回収する意図を表すオブジェクトで、決済プロセスのライフサイクルの各段階を追跡します。

サーバー側

まず、サーバーで PaymentIntent を作成し、回収する金額と通貨 usd を指定します。Payment Intents API を使用した実装がすでにある場合は、PaymentIntent の支払い方法タイプのリストに us_bank_account を追加します。オプションで、Customer の ID を指定します。

将来その支払い方法を再利用する場合には、値を off_session に設定して setup_future_usage パラメーターを指定します。

デフォルトでは、銀行口座の支払い情報の収集では、手動の口座番号入力と少額入金の確認のフォールバックオプションを使用し、Financial Connections で顧客のアカウントを即時確認します。Financial Connections を設定し、ACH の実装を最適化するために追加の口座データにアクセスする方法については、Financial Connections に関するドキュメントをご覧ください。たとえば、Financial Connections を使用して、ACH 決済の開始前にアカウントの残高を確認できます。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account

クライアント側

返される PaymentIntent には client secret が含まれています。これは、PaymentIntent オブジェクト全体を渡すことなく安全に決済を完了するために、クライアント側で使用されます。クライアント側で、サーバーに PaymentIntent をリクエストし、その client secret を保存します。

import UIKit
import StripePayments

class CheckoutViewController: UIViewController {
  var paymentIntentClientSecret: String?

  func startCheckout() {
      // Request a PaymentIntent from your server and store its client secret
  }
}

顧客はお客様のアプリから離れて、(Safari やバンキングアプリなどで) 認証する場合があります。ユーザーが認証後にアプリに自動的に戻れるようにするには、カスタム URL スキームを構成し、URL を SDK に転送するようにアプリのデリゲートを設定します。Stripe はユニバーサルリンクには対応していません。

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    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
    }
}

ACH ダイレクトデビットで決済を成功させるには、顧客の氏名と (オプションで) メールアドレスが必要です。アプリで、必要な請求詳細を顧客から収集します。

• 顧客の氏名 (姓と名)
• 顧客のメールアドレス

STPCollectBankAccountParams でクラス関数 collectUSBankAccountParams を使用し、collectBankAccountForPayment を呼び出すために必要なパラメーターを作成します。ACH ダイレクトデビット PaymentMethod を作成するには、billing_details パラメーターに口座名義人を含める必要があります。

STPBankAccountCollector のインスタンスを作成して collectBankAccountForPayment を呼び出し、銀行口座情報を収集し、PaymentMethod を作成し、その PaymentMethod を PaymentIntent に関連付けます。

// Build params
let collectParams = STPCollectBankAccountParams.collectUSBankAccountParams(with: name, email: email)

// (optional) Configure the style
let style: STPBankAccountCollectorUserInterfaceStyle = .alwaysLight
let bankAccountCollector = STPBankAccountCollector(style: style)

// Calling this method will display a modal for collecting bank account information
bankAccountCollector.collectBankAccountForPayment(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 が PaymentIntent に自動的に関連付けられます。

決済を開始する前に、同意書の規約を表示して顧客から承認を得る必要があります。

Nacha の運営規則に準拠するため、決済を開始する前に、同意書の規約を表示して顧客から承認を得る必要があります。同意書の詳細については、こちらの記事をご覧ください。

顧客が同意書の規約を承認する際に、お客様は PaymentIntent を確定する必要があります。顧客がフォームを送信したら、confirmPayment を使用して、決済を完了します。

let paymentIntentParams = STPPaymentIntentParams(clientSecret: clientSecret,
                                            paymentMethodType: .USBankAccount)

STPPaymentHandler.shared().confirmPayment(
    paymentIntentParams, with: self
) { (status, intent, error) in
    switch status {
    case .failed:
        // Payment failed
    case .canceled:
        // Payment was canceled
    case .succeeded:
        // Payment succeeded
    @unknown default:
        fatalError()
    }
}

成功した場合、Stripe から以下のいずれかのステータスで PaymentIntent オブジェクトが返されます。

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

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

このような場合、Stripe は descriptor_code による少額入金を送金し、銀行口座の確認でさらに問題が発生した場合には、amount による少額入金に戻る場合があります。これらの入金が顧客のオンライン明細書に表示されるには 1 ～ 2 営業日かかります。

• 明細書表記コード。Stripe は、SM で始まる一意の 6 桁の descriptor_code を使用し、0.01 USD の 1 件の少額入金を顧客の銀行口座に送金します。顧客は、この文字列を使用して銀行口座を確認します。
• 金額。Stripe は、ACCTVERIFY という明細書表記を使用し、一意でない 2 件の少額入金を顧客の銀行口座に送金します。顧客は、この入金額を使用して銀行口座を確認します。

前のステップで行った confirmPayment メソッドの呼び出しの結果として、requires_action 状態のPaymentIntentが返されます。この PaymentIntent には、確認を完了するための有益な情報を含む next_action フィールドが含まれています。

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

オプション: カスタムのメール通知を送信する

また、顧客にカスタムのメール通知を送信することもできます。カスタムメールを設定した後は、顧客が確認メールに応答する方法を指定する必要があります。以下の方法のうち、いずれか _1 つ_を指定してください。

• Stripe 上のオンライン確認ページを使用します。これを行うには、next_action オブジェクトの 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] の値を確認します。

// Use if you are using a descriptor code, do not use if you are using amounts
STPAPIClient.shared.verifyPaymentIntentWithMicrodeposits(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.verifyPaymentIntentWithMicrodeposits(clientSecret: clientSecret,
                                                         firstAmount: firstAmount,
                                                         secondAmount: secondAmount,
                                                         completion: { intent, error in
})

銀行口座の確認が成功すると、Stripe は、processing の status の PaymentIntent オブジェクトを返します。

確認が失敗する理由はいくつかあります。失敗は、直接的なエラー応答として同期的に発生します。

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

ACH ダイレクトデビットは、通知遅延型の支払い方法です。このため、顧客の口座から引き落としを開始してから、決済の成功または失敗の通知を受けるまでに最大で 4 営業日かかります。

PaymentIntent を作成すると、その初期ステータスは processing となります。決済が成功すると、PaymentIntent のステータスは processing から succeeded に更新されます。

Webhook を使用して決済が成功したことを確認し、顧客に決済完了を通知することをお勧めします。Stripe ダッシュボードでイベントを表示することもできます。

Financial Connections を使用して即時確認を行うシナリオをテストする方法をご紹介します。

サンドボックスで取引メールを送信する

銀行口座の詳細を収集し、同意書を受け付けたら、サンドボックスで同意書の確認メールと少額入金の確認メールを送信します。

ドメインが {domain} でユーザー名が {username} の場合、{username}+test_email@{domain} というメール形式を使用してテスト取引メールを送信してください。

たとえば、ドメインが example.com でユーザー名が info の場合、ACH Direct Debit 決済のテストには info+test_email@example.com という形式を使用します。この形式により、メールが正しくルーティングされます。+test_email サフィックスを含めない場合、メールは送信されません。

テスト用口座番号

Stripe では、手動入力の銀行口座の組み込みが本番環境に移行する準備が整ったかどうかを確認するため、テスト用の口座番号と対応するトークンをいくつか用意しています。

テスト取引を完了する前に、自動的に支払いに成功または失敗するテスト用のすべての口座を確認する必要があります。確認するには、下記の少額入金のテスト用の金額または明細書表記コードを使用します。

少額入金の金額と明細書表記コードをテストする

さまざまなシナリオを再現するために、これらの少額入金の金額「または」明細書表記コードの値 0.01 を使用します。

売上処理の動作をテストする

テスト取引は即座に売上として処理され、利用可能なテスト残高に追加されます。この動作は、利用可能な残高で取引が売上として処理されるまでに数日かかることがある、本番環境とは異なります。