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

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

利用シーン

3Dセキュア義務化要件における、「契約内容や購入品目の追加変更があった場合の 3Dセキュア認証」の実施手段としてご利用いただけます。

顧客カードに対する 3Dセキュアは認証が失敗してもそのカードが使用不可となったりはせず、その認証結果をどう扱うかは完全に加盟店様の実装によって決められる、比較的自由度が高い機能となっております。

決済時に 3Dセキュアを行いたい場合は支払い時の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 にリダイレクトされます。
サーバーサイドにて認証結果を確認してください。

※ 戻り先 URL にリダイレクトされる時に、PAY.JPから特別なパラメーターが付与されたりすることはありません。
開始エンドポイントへの誘導前にあらかじめリソースのIDをセッションなどに保持しておいてください。

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セキュアでは、認証の結果はカードオブジェクトの状態に影響を与えないため、失敗であっても使えなくなったりはしません。