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 "three_d_secure=true" # このパラメーターを追加してください
作成された支払いは決済の成否を表す paid 属性が false になっており、決済処理はまだ行われていない状態になっています。
また、3Dセキュアの認証状態を表す three_d_secure_status 属性が unverified になっており、これによって 3Dセキュア処理待ちであることが示されています。
注意：3Dセキュア開始から一定時間以内に支払い完了まで到達しない場合、その支払いの 3Dセキュアを進めることができなくなります。
このあとは3Dセキュアワークフローを選択する必要があります。
サブウィンドウ型
サブウィンドウ型の概要についてはPAY.JP における 3D セキュア - ●サブウィンドウ型をご覧ください。
3D セキュア認証画面を表示するサブウィンドウを表示し、購入者はその内部に表示されるカード発行会社の画面上でパスワード入力等を行います。
誘導には、payjp.js v2 が提供する openThreeDSecureDialog 関数を利用します。
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')
payjp.openThreeDSecureDialog(
'サーバーサイドから渡された支払いID'
).then(() => {
// 3Dセキュア処理が終了したことをサーバーサイドに通知する
})
openThreeDSecureDialog を呼び出すと、3D セキュア認証画面がサブウィンドウで開かれます。
購入者が 3D セキュア認証を終了させることでサブウィンドウは自動的に閉じられ、Promise が解決されます。
Promise が解決されたことが確認できたら、再度サーバー側に処理を移し、次項の支払い完了処理を行います。
サブウィンドウ型での注意事項
下記に列挙するような環境ではポップアップに対して警告やブロックが働くため、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セキュア開始 をご覧ください。
処理完了、あるいはエラーとなったタイミングで、利用者は指定した戻り先 URL にリダイレクトされます。戻り先 URL では次項の支払い完了処理を行います。
※ 戻り先 URL にリダイレクトされる時に、PAY.JP から特別なパラメーターが付与されたりすることはありません。 開始エンドポイントへの誘導前にあらかじめリソースの ID をセッションなどに保持しておいてください。
支払いの3Dセキュアを完了させる
カード発行会社における認証の終了を検知したら、サーバーから 3Dセキュア完了エンドポイントにリクエストします。
curl -X POST https://api.pay.jp/v1/charges/支払いID/tds_finish \
-u sk_test_c62fade9d045b54cd76d7036:
3Dセキュア認証が正しく行われていれば、決済処理が行われ、通常の支払い作成と同様のレスポンスが返却されます。
より細やかな制御をする場合は、3Dセキュア完了エンドポイントにリクエストする前に支払いオブジェクトを取得し直し、下記の項目のような実装をご検討ください。
完全認証を行いたい場合
取得されたオブジェクトの three_d_secure_status が attempted の場合に購入手続きを中断することで、完全認証となります。それ以外にも、商品や金額等をふまえて加盟店独自の基準で制御することも可能です。
three_d_secure_status が失敗状態のとき
unverified のままであったり、error であったりする場合は、3D セキュアの手順中に離脱した、パラメーターに異常があった等の問題が考えられます。この状態では 3D セキュア完了エンドポイントへのリクエストもエラーとなるため、支払いの作成から 3D セキュアフローをやり直す必要があります。
attempted または verified の場合は 3Dセキュア完了が可能です。
3Dセキュア認証の追加項目に対応する
概要についてはPAY.JPにおける3Dセキュア - 3Dセキュア認証における追加項目をご覧ください。
追加項目に対応するには、下記のどちらかのタイミングで必要な情報をカードにセットする必要があります。
トークン作成時にカード情報と共に入力させる
トークン作成時の3Dセキュア - 3Dセキュア認証の追加項目に対応するを参考に、各ライブラリで情報をセットしてください。
トークン作成時以外で入力させる
任意のタイミングで、有効なカード名義、および電話番号またはメールアドレスをエンドユーザーに入力してもらってください。
収集した追加項目は顧客カード更新のAPIにてセットできます。
curl https://api.pay.jp/v1/customers/cus_xxxxxx/cards/car_xxxxxxxxx \
-u sk_test_c62fade9d045b54cd76d7036: \
-d name="PAY TARO" \
--data-urlencode "email=pay@example.local" \
--data-urlencode "phone=+0819001234567" \
※顧客に登録したカードのみ追加項目の更新が可能です。
追加項目について
連携していただくメールアドレスおよび電話番号等の情報は、カード発行会社に登録されているデータと完全に一致している必要はありません。
カード会社の登録情報との一致を目指すものではなく、リスク判定のための情報の1つとして利用されます。
そのため、加盟店様に登録されている顧客情報や購入時の情報など、購入者自身が入力したものをご連携いただければ問題ありません。
これらのことから、追加項目の更新は顧客に登録したカードに対してのみ可能となっています。
作成したトークンを顧客に登録せずに支払いに使う場合、追加項目の更新はできませんのであらかじめご了承ください。
このようなケースは都度購入などで想定されますが、トークン作成から支払い確定までにメールアドレスや電話番号の変更があったとしても、トークン作成時に入力された値をそのままセットしていただいて問題ございません。