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セキュアワークフローを選択する必要があります。
iframe型
iframe型の概要についてはPAY.JP における 3D セキュア - ●iframe型をご覧ください。
3D セキュア認証画面を表示するiframeを表示し、購入者はその内部に表示されるカード発行会社の画面上でパスワード入力等を行います。
誘導には、payjp.js の openThreeDSecureIframe 関数を利用します。
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')
// iframe型の場合
payjp.openThreeDSecureIframe(
'サーバーサイドから渡された3DセキュアリクエストID'
).then(() => {
// 3Dセキュアフロー終了を加盟店サーバーに通知
fetch("https://example.com/finish_3ds_authentication", {method: 'POST'}) // リクエスト例
}).catch((error) => {
// エラーを加盟店サーバーに通知
fetch("https://example.com/finish_3ds_authentication", {method: 'POST', body: JSON.stringify(error)}) // リクエスト例
})
誘導関数を呼び出すと、3D セキュア認証画面が同画面上のiframeで開かれます。
購入者が 3D セキュア認証を終了させることで子画面は自動的に閉じられ、Promise が解決されます。
Promise が解決されたことが確認できたら、3Dセキュアは完了となります。
サーバーサイドにて認証結果を確認してください。
リダイレクト型
リダイレクト型の概要についてはPAY.JP における 3D セキュア - ●リダイレクト型をご覧ください。
3D セキュア認証を進めるためにエンドユーザーをカード会社が提供する 3D セキュア認証画面に誘導します。
3Dセキュア開始エンドポイントへエンドユーザーを誘導する際の詳細な仕様については APIリファレンス - 3Dセキュア開始 をご覧ください。
処理完了、あるいはエラーとなったタイミングで、3Dセキュアは完了となり利用者は指定した戻り先 URL にリダイレクトされます。その後、サーバーサイドにて認証結果を確認してください。
※ 戻り先 URL にリダイレクトされる時に、PAY.JP から特別なパラメーターが付与されたりすることはありません。 開始エンドポイントへの誘導前にあらかじめリソースの ID をセッションなどに保持しておいてください。
サブウィンドウ型
サブウィンドウ型の概要についてはPAY.JP における 3D セキュア - ●サブウィンドウ型をご覧ください。
サブウィンドウ型は処理がサブウィンドウ内で行われること以外ほぼiframe型と挙動や実装方法が同じです。
iframe型の openThreeDSecureIframe をコールしている箇所を openThreeDSecureDialog 関数に置き換えることでサブウィンドウを使用できます。
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セキュアでは、認証の結果はカードオブジェクトの状態に影響を与えないため、失敗であっても使えなくなったりはしません。
このような仕様となっている経緯としては、例えば下記のような場合にカードが使えなくなってしまうと不都合が生じるためです。
- 例:
- すでに定期課金を購読している顧客カードがあった場合
- この顧客カードを使用している利用者が新規に別の定期課金を購読したい時にその操作者が正規の利用者であるかどうか認証するため、顧客カードに対する3Dセキュアを実施
- この時認証に失敗してしまった場合、本来であれば新規の定期課金購読が不可である、とするのが目的ですが、顧客カード自体を決済不可としてしまうと現在購読中の定期課金の継続が不可能となってしまう
このように顧客カードに対する3Dセキュアが失敗した場合にそのカードが使えなくなる仕様としてしまうと様々な操作時に3Dセキュア認証を組み込みたい時、意図と違う決済不可という状況が発生してしまうことが想定されるため、認証結果の扱いに関しては加盟店様側でハンドリングを行なっていただく仕様としています。