Payment Intents API と Payment Methods API に移行する

Sources API および Tokens API から Payment Methods API に移行する方法をご紹介します。

支払い情報の収集と保管の導入に推奨される方法は、既存の Tokens API と Sources API を使用する方法から、Payment Methods API を使用する方法に変わりました。この API は Payment Intents API と連携して、多種多様な支払い方法による支払いを作成できます。

Stripe は、Sources API での現地の支払い方法のサポートを終了する予定です。現在 Sources API を使用して現地の支払い方法を処理している場合は、Payment Methods API に移行する必要があります。Sources API と Tokens API のサポート終了に関する詳細については、メール通知をお送りします。

カードによる支払い方法への対応を無効にする予定はありませんが、Payment Methods API と Payment Intents API への移行をお勧めしています。カードによるお支払い方法の移行について詳細は、Payment Intents API への移行をご覧ください。

現地の支払い方法を Sources API から Payment Intents API に移行する

現地固有の支払い方法の連携を移行するには、PaymentIntents API を使用するように、サーバーとフロントエンドを更新します。一般的な連携オプションは以下の 3 つです。

決済フローの Stripe Checkout にリダイレクトする。
自社の決済ページで Stripe の Payment Element を使用する。
自社のフォームを作成し、Stripe JS SDK を使用して支払いを完了する。

Stripe Checkout または Payment Element を使用する場合、コードを変更せずに Stripe ダッシュボードからほとんどの支払い方法を追加したり管理したりできます。

Payment Methods API を使用して現地固有の支払い方法を導入する方法について、詳細は支払い方法に関するドキュメントで、その支払い方法の手順をご確認ください。次の表は、各支払いタイプの比較概要です。

以前の実装	Stripe Checkout	Payment Element	自社のフォーム
	複雑度: 低	複雑度: 中	複雑度: 高
フロントエンドまたはサーバーで Source を作成する	サーバーで Checkout セッションを作成する	サーバーで PaymentIntent を作成する	サーバーで PaymentIntent を作成する
ウィジェットを読み込むか、サードパーティーにリダイレクトして支払いを承認する	不要	client secret をフロントエンドに渡し、Stripe JS SDK を使用して Payment Element をレンダリングし、支払いを完了する	client secret をフロントエンドに渡し、自社のフォームを使用して顧客から追加情報を収集し、支払い方法に応じて支払いを完了する
Source が請求可能であることを確認し、請求する	不要	不要	不要
支払いが成功したことを、`charge.succeeded` Webhook を使用して非同期で確認する	Checkout セッションが成功したことを `payment_intent.succeeded` Webhook で確認する	PaymentIntent が成功したことを `payment_intent.succeeded` Webhook で確認する	PaymentIntent が成功したことを `payment_intent.succeeded` Webhook で確認する

注意

PaymentIntent オブジェクトは、新しい実装での支払いを表し、フロントエンドで支払いを確認すると Charge を作成します。これまでデータベースに Charge への参照を保存していた場合は、顧客が支払いを完了した後に PaymentIntent から Charge ID を取得することで、引き続き保存できます。ただし、PaymentIntent ID も保存しておくことをお勧めします。

支払いステータスの確認

以前は、実装で API コールのたびに Source と Charge の両方のステータスを確認する必要がありましたが、今後は 2 つのステータスをチェックする必要はありません。フロントエンドでの確定後に、PaymentIntent または Checkout セッションのステータスを確認するだけで済みます。

payment_intent.status	意味	特記事項
`succeeded`	支払いが成功しました。	該当しない
`requires_payment_method`	支払いが失敗しました。	該当しない
`requires_action`	顧客は支払いの承認を完了していません。	顧客が 48 時間以内に支払いを完了しない場合、PaymentIntent は `requires_payment_method` に移行し、確定を再試行できるようになります。

PaymentIntent のステータスは、必ずサーバーで取得するか、サーバーで Webhook をリッスンして確認してください。PaymentIntent を確定する際に指定される return_url にユーザーが戻ることのみで判断しないようにしてください。

返金

PaymentIntent が作成した Charge を使用して、引き続き Refunds API を呼び出すことができます。Charge の ID は latest_charge パラメーターで確認できます。

または、Refunds API に Charge の代わりに PaymentIntent ID を指定することもできます。

エラー処理

これまでは、Source でエラーを処理する必要がありました。PaymentIntents を使用する場合、Source でエラーを確認する代わりに、PaymentIntent の作成時と顧客が支払いを承認した後に PaymentIntent のエラーを確認する必要があります。PaymentIntent のエラーのほとんどは、無効なリクエストで返された invalid_request_error タイプによるものです。

実装を移行する際は、PaymentIntent のエラーコードが Sources の対応するエラーコードと一致しない場合があることにご注意ください。

Webhook

これまで Source イベントをリッスンしていた場合は、新しいイベントタイプをリッスンするように、構築済みのシステムの更新が必要になる場合があります。次の表は、いくつかの例を示しています。

以前の Webhook	Checkout の新しい Webhook	PaymentIntent の新しい Webhook	特記事項
`source.chargeable`	該当しない	該当しない
`source.failed`	該当しない	該当しない
`source.canceled`	該当しない	該当しない
`charge.succeeded`	`checkout.session.completed`	`payment_intent.succeeded`	`charge.succeeded` Webhook も送信されるため、新しい Webhook をリッスンするように、構築済みのシステムを更新する必要はありません。
`charge.failed`	適用されません。顧客は有効期限が切れるまで同じ Checkout セッションで支払いを再試行でき、有効期限が切れた時点で `checkout.session.expired` イベントが届きます。	`payment_intent.payment_failed`	`charge.failed` Webhook も送信されるため、新しい Webhook をリッスンするように、構築済みのシステムを更新する必要はありません。
`charge.dispute.created`	`charge.dispute.created`	`charge.dispute.created`

Payment Methods API に移行する

Payment Methods API と Sources API の主な違いは、Sources API が status (ステータス) プロパティによって取引状態を表す点にあります。各 Source オブジェクトが支払い可能な状態に移行するまで、支払いに使用することはできません。対照的に、PaymentMethod にはステータスプロパティがなく、PaymentIntent オブジェクトに依存して、支払い状態を表します。

注

以下の表には、すべての支払い方法が掲載されているわけではありません。Sources API を使用してこの他の支払い方法を導入している場合は、それらも同様に Payment Methods API に移行してください。

フロー	Payment Intents API を使用して支払い方法を導入する	Charges API を使用した Tokens と Sources
カード	カード支払い	Token ではサポート対象: Sources では非推奨
ACH ダイレクトデビット	アメリカの銀行の (ACH) ダイレクトデビット	Tokens ではサポート対象、Sources では対象外
Alipay	Alipay での支払い	非推奨
Bancontact	Bancontact での支払い	非推奨
EPS	EPS での支払い	非推奨
giropay	giropay での支払い	非推奨
iDEAL	iDEAL による支払い	非推奨
Klarna	Klarna での支払い	非推奨
Multibanco	Multibanco による支払い	非推奨ベータ
Przelewy24	Przelewy24 での支払い	非推奨
SEPA ダイレクトデビット	Single Euro Payments Area (SEPA) ダイレクトデビット	非推奨
Sofort	Sofort での支払い	非推奨
WeChat Pay	WeChat Pay での支払い	非推奨

実装する API を選択した後で、支払い方法ガイドを参照すると、サポートが必要な適切な支払い方法タイプを判断しやすくなります。

このガイドには各支払い方法の詳細が記載され、顧客対応フローの違いと、その支払い方法に最も適した地域について説明されています。利用可能な支払い方法は、ダッシュボードで有効にできます。通常は即時に有効化され、追加の契約は必要ありません。

レガシーの再利用可能な支払い方法との互換性

すでに Sources を使用して、以下の再利用可能な支払い方法のいずれかを処理したことがある場合、既存の保存されたソースの自動移行は行われません。

Alipay
Bacs ダイレクトデビット
SEPA ダイレクトデビット

既存の顧客の保存済みの支払い方法を保持するには、Stripe ダッシュボードのデータ移行ツールを使用して、これらのソースを支払い方法に変換する必要があります。これらを変換する手順については、サポートページをご覧ください。

レガシーのカードオブジェクトとの互換性

すでに cards または Sources を使用して Stripe でカード顧客の支払い詳細を収集したことがある場合は、支払い情報を移行することなく、すぐに Payment Methods API の使用を開始できます。

Customer に保存された互換性のある支払い手段は、PaymentMethod オブジェクトを受け付けるすべての API で使用できます。たとえば、PaymentIntent を作成するときは、保存したカードを PaymentMethod として使用できます。

オブジェクトを PaymentIntent に関連付けるときは、互換性のある支払い手段の保存先である顧客 ID を忘れずに指定してください。

Payment Methods API を使用することで、保存されている互換性のある支払い方法のすべてを取得できます。

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "card",
  "address_city": "San Francisco",
  "address_country": "US",
  "address_line1": "1234 Fake Street",
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

この互換性があるために、新しいオブジェクトは作成されません。Payment Methods API は、基となるオブジェクトが同じでありながら、提供されるビューが異なります。たとえば、Payment Methods API で互換性のある支払い手段を更新した場合、その更新は Sources API でも表示され、また、その逆も同様です。