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セキュアワークフローを選択する必要があります。
サブウィンドウ型
サブウィンドウ型の概要についてはPAY.JP における 3D セキュア - ●サブウィンドウ型をご覧ください。
3Dセキュア認証画面を表示するサブウィンドウを表示し、エンドユーザーはその内部に表示されるカード発行会社の画面上でパスワード入力等を行います。
誘導には、payjp.js v2 が提供する openThreeDSecureDialog 関数を利用します。
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')
payjp.openThreeDSecureDialog(
'サーバーサイドから渡された3DセキュアリクエストID'
).then(() => {
// 3Dセキュア処理が終了したことをサーバーサイドに通知する
})
openThreeDSecureDialog を呼び出すと、3Dセキュア認証画面がサブウィンドウで開かれます。
エンドユーザーが 3Dセキュア認証を終了させることでサブウィンドウは自動的に閉じられ、Promise が解決されます。
Promise が解決されたことが確認できたら、3Dセキュアは完了となります。
サーバーサイドにて認証結果を確認してください。
サブウィンドウ型での注意事項
下記に列挙するような環境ではポップアップに対して警告やブロックが働くため、3Dセキュアが行えない場合がございます。
それを踏まえた上でご利用いただくか、リダイレクト型での実装をご検討ください。
1. ポップアップブロック
ブラウザごとのデフォルト値やユーザー設定によって、ポップアップブロック機能が有効化されている場合があります。
そのような環境からサブウィンドウ型での 3Dセキュア認証を実行しようとした場合、サブウィンドウの起動がブロックされ認証ができません。
サブウィンドウ型をそのような環境の利用者に使ってもらうには下記の対応が考えられます。
- ポップアップブロック機能を無効化してからカード情報を入力してもらう
- ポップアップがブロックされた際にブラウザ URL バー付近のポップアップブロック通知からポップアップを許可する
※ 2 で許可を選ぶとポップアップまたは新規タブにおいて、カード会社による 3Dセキュア認証画面が現れますが、ブロックされた時点でその認証は無効となります。
その場合再度カード情報の入力からやり直してください。
上記が難しい場合、リダイレクト型に切り替える必要があります。
2. Cross-Origin-Opener-Policyヘッダー
加盟店様サイト側でレスポンスヘッダーに Cross-Origin-Opener-Policy を設定している場合にサブウィンドの起動がブロックされる場合があります。
この場合はサイト側のヘッダー設定を変更していただくか、リダイレクト型に切り替える必要があります。
3. モバイルアプリブラウザ
モバイルアプリ内のブラウザはその中で別タブを開いたりといった機能に基本的に対応していません。
そのためサブウィンドウ型は動作しませんので、モバイル SDKのご利用をご検討いただくか、リダイレクト型に切り替える必要があります。
リダイレクト型
リダイレクト型の概要についてはPAY.JP における 3D セキュア - ●リダイレクト型をご覧ください。
3D セキュア認証を進めるためにエンドユーザーをカード会社が提供する 3D セキュア認証画面に誘導します。
3Dセキュア開始エンドポイントへエンドユーザーを誘導する際の詳細な仕様については 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セキュアでは、認証の結果はカードオブジェクトの状態に影響を与えないため、失敗であっても使えなくなったりはしません。