ACH Direct Debit を Charges API から新しい API に移行する

Charges API から移行する理由と方法をご紹介します。

Stripe is removing support for ACH Direct Debit using legacy integrations.

If you create legacy ACH Direct Debit payments, you must migrate to the Payment Intents API or Checkout Sessions API.

Feature comparison

Stripe’s new APIs offer features that aren’t available in legacy integrations:

機能	Legacy Integrations	Payment Intents API または Checkout Sessions API
Checkout サポート	いいえ	はい
Payment Element のサポート	いいえ	はい
動的な決済手段への対応	いいえ	はい
売上処理速度	T+6	T+4 (売上処理の高速化を使用する場合の T+2)
銀行口座の即時確認	カスタムのサードパーティーとの統合でのみ利用可能	Financial Connections による即時認証
Fraud prevention	いいえ	Radar for ACH Financial Connections を使用した残高チェック Smart Retries
対応可能な国	アメリカ	アメリカ、EU、イギリス

Checkout Sessions API と Payment Intents API の比較

Stripe offers two new APIs to accept ACH Direct Debits payments: Payment Intents and Checkout Sessions APIs.

Checkout Sessions API: ビルトイン機能を使って一般的なチェックアウトのワークフローをサポートします。これはカスタムコードが不要で、ほとんどの開発者に推奨されています。
Payment Intents API: 独自の決済フローを構築するための下位レベルの API。非常に多くのコードと継続的なメンテナンスが必要です。ほとんどの組み込みには Checkout Sessions をお勧めします。

その違い、そしてどちらが適切かを判断する方法について、詳しくはこちらをご覧ください。

ACH Direct Debit 統合の構築

PaymentIntents または Checkout Sessionsで ACH Direct Debit の連携を構築するには:

支払い方法の設定で ACH Direct Debit を有効にします。
新しい決済方法を収集して使用するには ACH on Payment Intents または Checkout Sessions を連携してください。
For bank accounts previously collected using the Tokens API, you can continue to use saved BankAccount objects as PaymentMethod objects with the Payment Intents API. For details, see Migrate existing bank accounts.
インテグレーションをテストする。
既存の銀行口座を使ったすべての支払いを、段階的に Payment Intents または Checkout Sessions API に移行してください。
Remove your legacy integration.

Behavioral differences

Some features that exist in both APIs work differently. If you rely on any of the following behaviors, update your integration accordingly.

Behavior	Legacy Integrations	Payment Intents or Checkout Sessions API
Mandates	Not enforced by the API.	Enforced by the API. Payments can’t be initiated without an active mandate. Mandates can become inactive, which renders the payment method unusable. This can occur when a customer disputes a payment, when certain payment failures occur, or when Stripe becomes aware that the payment method is no longer valid. For more information, see Blocked bank accounts. If you reuse bank accounts created with the Tokens API, you must first create mandates for them. See Migrate existing bank accounts.
Balance transactions	Created when the charge is created. The `Balance transaction` object is present in the `charge.pending` event and the API response.	Created when the payment is submitted to the banking partner. The `Balance transaction` object is present in the `charge.updated` event, but not the API response.
残高タイプ	Funds settle in `source_type=bank_account`.	Funds settle in `source_type=card`, shared with cards and other payment methods. If you manually specify the balance type for payouts or Connect transfers, update your integration to use the new balance type. During migration, you receive one payout for each balance type until all new payments use the new API. For separate charges and transfers with `source_transaction`, wait for the `charge.updated` webhook before creating a transfer.
少額入金	Two microdeposits of random, small amounts for verification. No hosted verification UI.	One 1¢ microdeposit with a descriptor code for verification. In rare cases, Stripe sends two microdeposits of random, small amounts instead. Stripe provides a hosted verification page and sends automatic reminder emails to customers. Customers must verify their bank account within 10 days. If they don’t verify in time, the PaymentIntent or SetupIntent reverts to requiring new payment method details.
Emails	Stripe doesn’t send automatic emails.	Stripe automatically emails customers a mandate confirmation when mandates are created. When a customer attempts to verify a bank account using microdeposits, Stripe emails customers with a link to a hosted verification page. You can disable Stripe emails and send custom notifications instead. For sample mandate text and required content, see Mandate and microdeposit emails.

Webhook differences

If you previously listened to Charge events, you might need to update your integration to listen to new event types. The following table shows how webhook events differ.

Old webhook	New webhook on Checkout	New webhook on Payment Intents	Special instructions
`charge.pending`	`payment_intent.processing`	`payment_intent.processing`	In legacy integrations, `charge.pending` includes balance transaction. In new integrations, the balance transaction isn’t available until the `charge.updated` event.
`charge.updated`	`charge.updated`	`charge.updated`	Sent when the payment is submitted to the banking partner. Includes the balance transaction.
`charge.succeeded`	`checkout.session.completed`	`payment_intent.succeeded`	`charge.succeeded` Webhook も送信されるため、新しい Webhook をリッスンするように実装を更新する必要はありません。
`charge.failed`	Not applicable. The customer can re-attempt the payment on the same Checkout Session until it expires, at which point you receive a `checkout.session.expired` event.	`payment_intent.payment_failed`	`charge.failed` Webhook も送信されるため、新しい Webhook をリッスンするように実装を更新する必要はありません。
`charge.dispute.created`	`charge.dispute.created`	`charge.dispute.created`	Not applicable
Not applicable	`mandate.updated`	`mandate.updated`	Sent when a mandate becomes inactive.

Identify Legacy ACH Payments

On a Charge object, the payment_method_details.type property is ach_debit for the legacy integration and us_bank_account for the newer integration.

A legacy ACH payment is created when a legacy BankAccount is the payment source. This happens when:

You call the Create Charge API.
A Subscription or Invoice charges a customer whose default_source is a legacy BankAccount, and no default_payment_method is set on the customer, subscription, or invoice.
You call the Create PaymentIntent API with source set to a legacy BankAccount.

メモ