3Dセキュア必須化に備えて、StripeのCharges APIが使われている場所がないかを調査する方法

この記事では、Stripeダッシュボードを活用して現在は非推奨となっているCharges APIをシステムが利用しているかどうかを調査する方法を紹介します。2025年3月に必須化される3Dセキュアによる追加認証への対応を進めている方は、この記事を参考にシステムの組み込み状況を調査してみてください。

2025年3月から対応が必須となる3Dセキュアを利用した追加認証、Stripeを利用している場合、基本的には追加の対応はほとんど必要ありません。これはStripeが提供する決済ページや決済フォーム側に3Dセキュアの提供を行う仕組みが用意されているためです。

一方で次のようなケースでは、3Dセキュアを利用するための追加実装が必要です。

- **サーバー側で支払いの実行**（`confirm`）を行う支払いフローで、Payment Intents / Setup Intentsの`requires_action`状態を処理する仕組みが用意されていない場合
- 現在は非推奨の、**Charges API**を利用して決済フローを提供している場合
- サブスクリプションで、[3Dセキュア認証操作を依頼するメールを送信する機能](https://dashboard.stripe.com/settings/billing/automatic)を**オフ**にしている場合  
![スクリーンショット 2024-10-15 14.17.18.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/6c9fd575-2e0c-90cb-2117-05402633a6a1.png)

今回の記事では、このうちCharges APIを利用しているケースについて、紹介します。

## Charges APIは現在の3Dセキュア認証（ EMV-3DS ）に対応していない

[Charges API](https://docs.stripe.com/payments/charges-api)はかつてStripeを利用した決済フローを構築する際に利用されていたAPIで、現在は利用が非推奨となっているAPIの１つです。新しい組み込み方法である[Payment Intents API（決済処理へ利用する）](https://docs.stripe.com/payments/paymentintents/lifecycle)および[Setup Intents API(支払い情報の保存へ利用する)](https://docs.stripe.com/payments/setupintents/lifecycle)への移行が推奨されており、その理由の1つが3Dセキュア認証への対応です。

Charges APIはAPIが非推奨になった後から登場した、[EMV-3DS ( 3Dセキュア2 )](https://stripe.com/jp/guides/3d-secure-2)に対応していません。そして現在はCharges APIが対応している3Dセキュア1での認証はすでに日本で提供されておらず、2025年3月から必須化される3Dセキュア認証の必須化への対応が困難です。

https://stripe.com/jp/guides/3d-secure-2

そのため、Charges APIを利用した決済フローを提供している日本のユーザーは、3Dセキュア必須化への対応として、[Payment Intents API](https://docs.stripe.com/payments/paymentintents/lifecycle)および[Setup Intents API](https://docs.stripe.com/payments/setupintents/lifecycle)への移行を必ず行う必要があります。

## ワークベンチでCharges APIの呼び出し履歴を確認できる

Charges APIから移行を行うには、まず現在のシステムとStripe連携がどのような状態かを知る必要があります。システムは現在もCharges APIを利用しているのか。それともすでにPayment IntentsやSetup Intentsへの移行が完了しているのか。はたまたStripe Checkoutを利用したリダイレクト型の組み込みに切り替えているのか。システムがStripeのAPIをどのように利用しているかを把握することで、移行プロジェクトを立ち上げるべきかどうかの判断や、工数の見積もりなどを始めることができます。

システムがStripeのAPIをどのように利用しているかを把握するには、Stripeダッシュボードを使うことをお勧めします。ダッシュボードには、APIのリクエストログやWebhookイベントを調査するための[ワークベンチ](https://docs.stripe.com/workbench)機能が提供されています。これはダッシュボード右下にある**ワークベンチを展開**ボタンをクリックするか、[Shiftキー]と[`~`キー]を同時に入力することで、起動できる開発者向けの支援ツールです。

![スクリーンショット 2024-10-15 14.36.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/5ff91d75-7c71-3638-1abf-2a67dcd3c935.png)

ワークベンチを起動すると、APIログやイベント・エラーなど、調査対象のタブを含む画面が表示されます。Charges APIのような、特定のAPIが利用されているかを調査するには、**ログ**タブを選択します。ここではStripeのAPIがいつ・どんな内容で呼び出されたかを調べることができます。

![スクリーンショット 2024-10-15 11.57.42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/921d97a9-bb95-6da4-bcd7-a96a105f23aa.png)

ここでCharges APIが実際に利用されているかを調べてみましょう。フィルターとして用意されている**APIエンドポイント**を選択し、Charges APIを新しく作成する際に利用するパス(`/v1/charges`)と入力します。このフィルターを利用することで、特定のAPIパスに対するリクエストだけを調べることができます。

![スクリーンショット 2024-10-15 11.57.56.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/d5bc3e10-58de-528d-b84c-bc1f999d8ba5.png)

もしCharges APIが利用されている場合、このフィルターを設定すると`POST /v1/charges`のリクエストログが表示されます。


![スクリーンショット 2024-10-15 11.58.14.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/9703b3dc-42a9-9ffa-33bc-7ff74bcfd9f0.png)

ワークベンチでは、APIリクエスト内容の詳細も調べることができます。ここでは呼び出されたIPアドレスや、Stripe SDKが送信するユーザーエージェント情報などを利用して、どのアプリケーション・サービスからCharges APIが呼び出されたかを深掘りします。スクリーンショットの例では、`NodeBindings`がユーザーエージェントに含まれていることから、[stripe-node SDK](https://github.com/stripe/stripe-node)を利用したアプリケーションがCharges APIを利用していることがわかります。

![スクリーンショット 2024-10-15 14.44.26.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/b9a8b882-f78a-e919-f21c-42eb40292e33.png)

また、右側の詳細パネルをスクロールすると、APIリクエストのBodyも見ることができます。ここでリクエスト内容を調べることで、ソースコードを検索する際に検索キーワードとして使えるパラメータ名などを調べます。下のスクリーンショットでは、`tok_`から始まるIDを`source`として渡していることから、フロントエンド側のアプリケーションでTokens APIを利用した処理が実行されており、そこから決済フローが始まっていることが伺えます。

![スクリーンショット 2024-10-15 14.49.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/5b9fb868-829f-221d-335d-05203a8ba0ff.png)

Tokens APIが出てきましたので、フィルターを更新して`/v1/tokens`についても調べてみましょう。するとフロントエンドのSDKが作成したTokens API作成リクエストの履歴が出てきます。こちらの詳細データを見ると、アプリケーションのどのURLからリクエストが送信されたかが把握できます。あとはTokens / Charges APIが利用されたであろうページのURLをヒントに、アプリケーション側のフローやソースコードを調査することができます。

![スクリーンショット 2024-10-15 14.50.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/8e48d62f-73e8-8c5a-2ade-717804d8bdf5.png)

あとは[移行ドキュメント](https://docs.stripe.com/payments/payment-intents/migration)を参考にPayment Intents APIやSetup Intents APIへの移行を進めます。テスト・ステージング環境でコードを変更した後、ワークベンチのログを調べることで、Charges APIの呼び出し履歴が依然として追加されてきているかを調べましょう。呼び出し履歴がゼロになれば、Charges APIを利用した決済フローは顧客に提供されていないと判断できます。

## Charge succeededイベントはPayment Intentでも発生する

ワークベンチでCharges APIについて調査する際、必要な点が１つあります。それは「**Stripeが内部的にCharge APIを利用することがあること**」です。

ワークベンチの**イベント**タブを開くと、`charge.updated`や`charge.succeeded`イベントが発生していることが確認できます。しかし**ログ**タブを見るとCharges APIの呼び出し履歴が残っていないケースがあります。これはPayment Intents APIやCheckout Sessions APIで決済を行った時に、Stripeが内部的に処理を行っていることがあるからです。

イベントログでCharges APIが利用されているかどうかを確認するには、Chargeに関するイベントの詳細データを確認します。Chargesオブジェクトの中にある、`payment_intent`パラメータに`pi_`から始まる文字列が含まれているかをチェックしましょう。もし文字列が含まれている場合、そのイベントはPayment Intents APIやCheckout Sessions APIを利用した決済にて送信されたイベントであると判断できます。

![スクリーンショット 2024-10-15 12.01.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/d9cc80a0-1294-5f56-7ba9-d1ae00f3a820.png)

次のスクリーンショットのように、`payment_intent`が`null`の場合、これはCharges APIを利用した決済で発生したイベントである可能性が高いです。この場合はログタブに移動して、Charges APIの呼び出し履歴が残っているかを確認・調査しましょう。


![スクリーンショット 2024-10-15 12.02.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/9030c388-59f9-2464-2a18-ae4348db71d4.png)

## まとめ

クレジットカードの不正利用を減らすため、2025年3月以降のオンライン決済では3Dセキュア(3DS)による認証が必須となります。Stripeを利用している場合、基本的には追加の対応は不要です。

https://docs.stripe.com/payments/3d-secure/authentication-flow

ただしCharges APIを利用した決済フローを提供されているユーザーは、[Payment Intent](https://docs.stripe.com/payments/paymentintents/lifecycle)または[Setup Intent](https://docs.stripe.com/payments/setupintents/lifecycle)を利用した組み込みへのアップグレードが必要です。具体的なアップグレード方法については、Stripe Docsの移行方法に関するページをご確認ください。

https://docs.stripe.com/payments/older-apis

https://docs.stripe.com/payments/charges-api

もし現在運用している決済フローがCharges APIを利用したものかどうかが不明な場合は、今回紹介したワークベンチを利用することで、Charge APIがどこで呼び出されているかを調査できます。APIリクエスト内容の調査やエラーログの分析も行うことができますので、変更後の動作確認や不具合検証などにもお使いいただけます。

2025年3月の必須化に備えて、一度決済フローの現状について確認してみましょう。

## Stripeでの3Dセキュア義務化対応について知りたい方は、こちらもどうぞ

2025年3月より始まる3Dセキュア義務化に関する記事を複数用意しております。現在対応方法をお探し中の方は、ぜひこちらの記事もご覧ください。

https://qiita.com/hideokamoto/items/7920051d7476439e5a5e

https://qiita.com/hideokamoto/items/710f9f006fe59ab83b27

https://qiita.com/hideokamoto/items/0f6d4e5fa34e8e673140

https://qiita.com/hideokamoto/items/fa8223470ad75f5307d1

https://qiita.com/hideokamoto/items/c30eded3fa8cd73f1a93