3Dセキュアを実施することで、不正利用によるチャージバックの発生を抑制する効果が見込めます。 3Dセキュアの概要については、3Dセキュアガイド の各ドキュメントをご覧ください。
3Dセキュアを開始する
通常の支払い作成と同様のパラメータで支払いを作成します。その際、追加のパラメータ three_d_secure=true を指定することで、3Dセキュア処理待ち状態の支払いが作成されます。
3Dセキュア処理待ち状態の支払いを作成:
curl -X POST https://api.pay.jp/v1/charges \
-u sk_test_c62fade9d045b54cd76d7036: \
-d "amount=500" \
-d "currency=jpy" \
-d "card=tok_xxx" \
-d "capture=true" \
-d "three_d_secure=true"
作成された支払いは決済の成否を表すpaid属性がfalseになっており、決済処理はまだ行われていない状態になっています。
また、3Dセキュアの実施状態を表すthree_d_secure_status属性がunverifiedになっており、これによって3Dセキュア処理待ちであることが示されています。
3Dセキュア開始から一定時間以内に支払い完了まで到達しない場合、その支払いの3Dセキュアを進めることができなくなりますのでご注意ください。 具体的な時間はAPIドキュメントをご参照ください。
購入者を3Dセキュアに誘導する
3Dセキュア認証を進めるために、購入者をカード会社が提供する3Dセキュア認証画面に誘導します。
誘導の方法は サブウィンドウ型 と リダイレクト型 の2種類があります。
サブウィンドウ型
3Dセキュア認証画面を表示するサブウィンドウを表示し、購入者はその内部に表示されるカード発行会社の画面上でパスワード入力等を行います。
誘導には、payjp.js v2が提供するopenThreeDSecureDialog関数を利用します。支払いIDが必要になるため、誘導ページのレンダリングに支払いパラメータを含めるなどの方法でクライアントに支払いIDを連携する必要があります。
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')
payjp.openThreeDSecureDialog('サーバーサイドから渡された支払いID').then(() => {
// 3Dセキュア処理が終了したことをサーバーサイドに通知する
})
openThreeDSecureDialogを呼び出すと、3Dセキュア認証画面がサブウィンドウで開かれます。
購入者が3Dセキュア認証を終了させることでサブウィンドウは自動的に閉じられ、promiseが解決されます。
promiseが解決されたことが確認できたら、再度サーバー側に処理を移し、次項の支払い完了処理を行います。
リダイレクト型
サービスからPAY.JPが提供する3Dセキュア開始エンドポイントにリダイレクトさせ、認証完了後にサービスが指定するエンドポイントにリダイレクトで戻す方式です。
サブウィンドウ型に比べると少し実装は煩雑になりますが、一部モバイル環境ではサブウィンドウ型が適切に動作しない可能性があるため、より広い環境で動作させたい、サブウィンドウのユーザー体験が望ましくないといった場合にはリダイレクト型をご利用ください。
3Dセキュアを実施するタイミングで、利用者を下記エンドポイントにリダイレクトさせます。
リダイレクト時のパラメータとして、完了後の戻り先となるURLを指定します。指定には事前登録式の back および動的な指定が可能な back_url パラメータが使用できます。
処理完了、あるいはエラーとなったタイミングで、利用者は指定した戻り先URLにリダイレクトされます。戻り先URLでは次項の支払い完了処理を行います。
支払いを完了させる
3Dセキュアフローの完了を検知したら、サーバーから3Dセキュア完了エンドポイントにリクエストします。
curl -X POST https://api.pay.jp/v1/charges/支払いID/tds_finish \
-u sk_test_c62fade9d045b54cd76d7036:
3Dセキュア認証が正しく行われていれば、決済処理が行われ、通常の支払い作成と同様のレスポンスが返却されます。 3Dセキュアが成功だったとしても、通常の支払い作成同様、与信不足やカードの一時的な停止などにより決済が失敗し、失敗レスポンスが返却される可能性もある点にご注意ください。
より細やかな制御を行う場合は、3Dセキュア完了エンドポイントにリクエストする前に支払いオブジェクトを取得し直してください。
取得されたオブジェクトのthree_d_secure_statusが attempted の場合に購入手続きを中断することで、完全認証となります。それ以外にも、商品や金額を鑑みて加盟店独自の基準で制御することも可能です。
unverified のままであったり、 error であったりする場合は、3Dセキュアの手順中に離脱した、パラメータに異常があった等の問題が考えられます。この状態では3Dセキュア完了エンドポイントへのリクエストもエラーとなるため、支払いの作成から3Dセキュアフローをやり直す必要があります。