# PAY.JP EMV 3Dセキュア対応方針

対象ブランチ: `fix/payjp-3ds-20260516`

## 結論

現状の「注文時にカードを登録し、着用日11日前に自動決済する」設計では、カード登録時に3Dセキュア認証を必須化する。

登録時に3Dセキュア認証が完了したカードだけを有効カードとして保存し、注文・保管料更新・後日自動決済では3Dセキュア認証済みカードのみを利用する。

## 根拠

PAY.JPの3Dセキュア義務化要件では、支払い作成前に使うカードへの3Dセキュア、または支払い作成時の3Dセキュアが必要となる。

このサービスは後日自動決済があるため、決済実行時にユーザーを3Dセキュア画面へ誘導しづらい。そのため、ユーザーが画面上にいるカード登録時点で3Dセキュアを完了させるのが最も運用に合う。

参考:

- PAY.JP における 3D セキュア: https://docs.pay.jp/v1/guideline-payjp-three-d-secure
- トークン作成時の 3Dセキュア: https://docs.pay.jp/v1/token-tds
- 顧客カードに対する 3Dセキュア: https://docs.pay.jp/v1/customer-card-tds

## 実装方針

1. カード登録APIでPAY.JPカードを作成する。
2. 作成した顧客カードに対して3Dセキュアリクエストを作成する。
3. フロント側でPAY.JPのiframe型3Dセキュア認証を開始する。
4. 認証完了後、サーバー側で3Dセキュアリクエストを取得し、結果を確認する。
5. `three_d_secure_status` が `verified` または `attempted` の場合のみ、カードを有効化する。
6. 認証未完了・失敗・離脱の場合はカードを有効化しない。
7. 注文・保管料更新では、3Dセキュア認証済みの有効カードのみを利用する。

## 実装内容

- `user_cards` に3DセキュアリクエストID、認証ステータス、認証完了日時を保存する。
- カード登録APIは、カード作成後すぐに3Dセキュアリクエストを作成し、認証待ちとして返す。
- フロント側はPAY.JPの `openThreeDSecureIframe()` で認証画面を表示する。
- 認証完了後、サーバー側でPAY.JPの3Dセキュアリクエストを取得し、`verified` または `attempted` の場合のみカードを有効化する。
- 注文時のカード選択、支払いリンクのカード登録、保管サービス用カード登録、保管料更新課金を3Dセキュア認証済みカード前提にする。

## 既存カードの扱い

既存登録済みカードは3Dセキュア認証状態を持たないため、今回の実装後は有効カード一覧・注文利用対象から外れる。

本番反映前に既存ユーザーへカード再登録を案内するか、既存カードに対する3Dセキュア再認証導線を別途追加する必要がある。

## クライアント回答案

PAY.JP決済機能自体は実装されていましたが、EMV 3Dセキュア対応は未完了でした。

今回の対応では、カード登録時に3Dセキュア認証を必須化し、認証が完了したカードのみ登録完了・決済利用可能とします。

注文時点ではカードを登録し、着用日11日前に自動決済する運用のため、後日の決済タイミングではなく、ユーザーが画面操作しているカード登録時に認証を完了させる方針が最適です。