顧客カードに対する3Dセキュア

3Dセキュアの概要については、下記ドキュメントをご覧ください。

利用シーン

3Dセキュア義務化要件における、「契約内容や購入品目の追加変更があった場合の3Dセキュア認証」の実施手段としてご利用いただけます。
それ以外にもカード登録時、または決済時以外のタイミングで3Dセキュアを行いたい場合に使用してください。

3Dセキュアを開始する

3Dセキュアリクエストオブジェクトを作成することで、対象顧客カードに対する3Dセキュアを開始することができます。
顧客カードの作成方法等は顧客を作成するをご覧ください。

下記のように3Dセキュアリクエストを作成します。
3Dセキュアの対象としたいカードを resource_id に指定してください。

curl -X POST https://api.pay.jp/v1/three_d_secure_requests \
-u sk_test_c62fade9d045b54cd76d7036: \
-d resource_id=car_xxxxxx

これにより3Dセキュアリクエストオブジェクトが作成され、 tdsr_xxxxxx のようなIDのオブジェクトが返されます。
このオブジェクトは3Dセキュアの実施状態を表す state 属性が created になっており、これによって3Dセキュア処理待ちであることが示されています。

注意：3Dセキュア開始から一定時間以内に3Dセキュア完了まで到達しない場合、その3Dセキュアは期限切れとなり完了することができなくなります。
期限切れとなった3Dセキュアリクエストには expired_at 属性に値がセットされます。

エンドユーザーを3Dセキュアに誘導する

3Dセキュア認証を進めるために、エンドユーザーをカード会社が提供する3Dセキュア認証画面に誘導します。誘導の方法はリダイレクト型とサブウィンドウ型の2種類があります。

サブウィンドウ型

3Dセキュア認証画面を表示するサブウィンドウを表示し、エンドユーザーはその内部に表示されるカード発行会社の画面上でパスワード入力等を行います。
誘導には、payjp.js v2 が提供する openThreeDSecureDialog 関数を利用します。
一部環境（モバイルにおけるアプリ内ブラウザなど）ではポップアップに対して警告やブロックが働くため、利用者によっては認証画面に辿りつけないこともございます。
利用状況に応じてリダイレクト型もご検討ください。

const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

payjp.openThreeDSecureDialog(
  'サーバーサイドから渡された3DセキュアリクエストID'
).then(() => {
  // 3Dセキュア処理が終了したことをサーバーサイドに通知する
})

openThreeDSecureDialog を呼び出すと、3Dセキュア認証画面がサブウィンドウで開かれます。
エンドユーザーが 3Dセキュア認証を終了させることでサブウィンドウは自動的に閉じられ、Promise が解決されます。
Promise が解決されたことが確認できたら、3Dセキュアは完了となります。
サーバーサイドにて認証結果を確認してください。

リダイレクト型

サービスから PAY.JP が提供する 3Dセキュア開始エンドポイントにリダイレクトさせ、認証完了後にサービスが指定するエンドポイントにリダイレクトで戻す方式です。サブウィンドウ型に比べると少し実装は煩雑になりますが、一部モバイル環境ではサブウィンドウ型が適切に動作しない可能性があるため、より広い環境で動作させたい場合や、サブウィンドウのユーザー体験が望ましくない場合にはリダイレクト型をご利用ください。

3Dセキュアを実施するタイミングで、利用者を下記のエンドポイントにリダイレクトさせます。

https://api.pay.jp/v1/tds/:three_d_secure_request_id/start?publickey=....&back=...

リダイレクト時のパラメーターとして、完了後の戻り先となる URL を指定します。以下の 2 通りの指定ができます。

back
- PAY.JP の管理画面で事前に登録した戻り先 URL を使用する場合に指定します。登録時に設定した識別子を指定してください。
back_url
- 動的に戻り先 URL を指定する場合に使用します。JWS（JSON Web Signatures）形式のデータで、戻り先 URL を含めて指定します。 back_url を使用した実装はコードサンプルを参考にご実装ください。

エンドポイントとパラメーターの詳細はAPIリファレンス - 3Dセキュア開始をご覧ください。

処理完了、あるいはエラーとなったタイミングで、3Dセキュアは完了となり利用者は指定した戻り先 URL にリダイレクトされます。
サーバーサイドにて認証結果を確認してください。

3Dセキュア結果の取得

3Dセキュア認証処理が完了したら、下記のように3Dセキュアリクエストオブジェクトを取得し、認証結果を確認できます。

curl https://api.pay.jp/v1/three_d_secure_requests/tdsr_xxxxxxx \
-u sk_test_c62fade9d045b54cd76d7036:

3Dセキュア認証が正しく行われていれば、 state が finished の3Dセキュアリクエストオブジェクトが返却されます。
オブジェクトの three_d_secure_status が verified または attempted であれば3Dセキュア認証成功となります。
unverified や error であった場合は、3D セキュアの手順中に離脱した、認証に失敗した、パラメーターに異常があった等の問題が考えられます。

3Dセキュア結果の扱いについて

行った3Dセキュアの結果に関してどう扱うかは、加盟店様側でご判断ください。

判断の一例として、下記のような使い方を想定しています。

顧客カードに対する3Dセキュアの組み込み例

月に一度サービスの使用料を徴収する定期課金を行う場合。定期課金を行なっていた顧客がプランの変更をリクエストをしてきたが、そのエンドユーザーの操作が本当にカード保有者が行なっている操作かを確認するために顧客カードに対する3Dセキュアを行う。

エンドユーザーが行った3Dセキュアが認証成功だった場合、続けてプランの変更処理を実施する。
エンドユーザーが行った3Dセキュアが認証失敗だった場合、プランの変更処理を実施しない。

他の3Dセキュア方式との違い

トークン作成時の3Dセキュア、支払い作成時の3Dセキュアは対象オブジェクトの作成前に合わせて認証を行う性質上、3Dセキュアが失敗すればそのオブジェクトは無効なものとなります。
しかし顧客カードに対する3Dセキュアでは、認証の結果はカードオブジェクトの状態に影響を与えないため、失敗であっても使えなくなったりはしません。