トークン作成時の 3Dセキュア

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

注意事項

現在 Checkout での下記機能はプレリリース中となっております。 すぐにご使用可能ですが、必ずお知らせの「2024年2月以前に 3Dセキュア対応版の利用を開始する場合」をお読みいただいた上でご利用ください。

  • Checkout でのトークン作成時の 3Dセキュア機能
  • Checkout での追加項目入力機能
  • トークン 3Dセキュアの実施要否をパラメーターで指定する機能

3Dセキュアを開始する

通常と同様のパラメーターでトークンを作成します。その際、追加のパラメーター three_d_secure=true を指定することで、3Dセキュア処理待ち状態のトークンが作成されます。

作られた3Dセキュア処理待ち状態のトークンは、card.three_d_secure_status が unverified となっており、また3Dセキュアが完了するまで支払い等に使えない状態となります。

このパラメーターの指定方法は次項の中からお使いのライブラリの項目をご覧ください。

●Checkoutでの開始方法

Checkoutで3Dセキュアを開始するには、 data-payjp-three-d-secure 属性および data-payjp-three-d-secure-workflow を指定する必要があります。

属性 指定内容
data-payjp-three-d-secure "true" を指定してください。
data-payjp-three-d-secure-workflow ご利用いただきたい3Dセキュアワークフローを指定する必要があります。
サービス形態や実装にあわせて適切なものをご指定ください。

●payjp.jsでの開始方法

payjp.jsで3Dセキュアを開始するには、 createToken 関数の第二引数 data に three_d_secure を true で指定します。

記載の例がリファレンスの欄にございますので、そちらもあわせてご確認ください。

●モバイル SDKでの開始方法

モバイル SDKで3Dセキュアを開始するには、各SDKのカードフォーム開始時にオプションを指定します。
モバイル SDK - 3Dセキュア開始方法にてお使いのライブラリの項目の3Dセキュア開始方法をご覧ください。

全てのトークン作成に対し3Dセキュアを必須とする

管理画面 > API設定 > 3Dセキュア よりトークン3Dセキュアの実施モードを指定することで、パラメーターを指定することなく全てのトークン作成に3Dセキュアを必須とすることもできます。
この機能を有効化すると、各ライブラリでの3Dセキュアを開始するかどうかの引数は無視されます。

トークン作成時の3Dセキュアを行いたい場合、引数を指定するか、本機能を有効化してください。

3Dセキュア認証の追加項目に対応する

3Dセキュア認証を行う場合、カード番号・有効期限など必須の情報以外にも追加の認証項目として下記が求められます。

  • カード名義
  • メールアドレスまたは電話番号

必要となる背景は3Dセキュア認証 - 3Dセキュア認証の追加項目をご覧ください。
トークン作成時の 3Dセキュアを行う場合、これらも含めて利用者に入力してもらう必要があります。
お使いのクライアントライブラリに合わせて、設定をご確認ください。

●payjp.js

デフォルトの挙動では追加項目に対応できません。
createToken 関数の data 引数に下記項目を含める必要があります。

  • card[email]
  • card[phone] または card[name] のいずれか

payjp.js に追加項目の入力フォームを表示する機能はなく、加盟店様側で実装していただく必要がございますのでご注意ください。
設定方法の詳細に関しては payjp.js リファレンス - payjp.createTokenをご覧ください。

●Checkout

デフォルトの挙動ではカード名義は自動的に必須となりますが、メールアドレス・電話番号を入力するフォームは表示されません。
data-payjp-extra-attribute-email および data-payjp-extra-attribute-phone をご設定ください。
設定方法の詳細に関しては Checkout - 追加予定属性の一覧をご覧ください。

●モバイル SDK

最新バージョンではデフォルトで追加項目全ての入力が行われるようになっています。
カード情報入力画面へ遷移させる際に、 ExtraAttribute を設定することでメールアドレス・電話番号のどちらかだけにする、といった制御が可能です。
設定方法の詳細に関しては各 SDK での使い方をご参照ください。

カード名義は自動的に必須で入力されます。

3Dセキュアワークフローについて

Checkout または payjp.js をお使いの場合、3Dセキュアワークフロー組み込み方法を選択する必要があります。

モバイル SDK を使って 3Dセキュアを行う場合、ワークフローはこのどちらともなりません。
詳細な実装方法はモバイル SDK を利用して 3Dセキュアを導入するをご覧ください。

ワークフローの指定方法

ワークフローを変更するには、下記のようにパラメーターを指定します。

利用するライブラリ 利用したいワークフロー パラメーター指定方法
payjp.js サブウィンドウ型 特に指定しない場合、デフォルトでサブウィンドウ型となります。
payjp.js リダイレクト型 Payjp インスタンスの初期化時のoptionsに {threeDSecureWorkflow: 'redirect'} を渡します。
Checkout サブウィンドウ型 Checkout - 追加予定属性の一覧の data-payjp-three-d-secure-workflow に subwindow を渡します。
Checkout リダイレクト型 Checkout - 追加予定属性の一覧の data-payjp-three-d-secure-workflow に redirect を渡します。

サブウィンドウ型について

前項の方法に従いサブウィンドウ型を指定することで、このタイプを使用できます。
サブウィンドウ型では、実装手順の全てをライブラリが実施してくれます。
そのため、作成されたトークンは通常通り作成が完了したものと同じ状態で、かつ 3D セキュアの実施が完了した状態で戻ってきます。

一部環境（モバイルにおけるアプリ内ブラウザなど）ではポップアップに対して警告やブロックが働くため、利用者によっては認証画面に辿りつけないこともございます。
こういった環境にも対応したい場合、3Dセキュアの認証ワークフローをリダイレクト型へ変更することが可能です。

リダイレクト型について

リダイレクト型では 3Dセキュア開始エンドポイントへのエンドユーザー誘導・3Dセキュア完了エンドポイントへのリクエストなどの実装を加盟店様側で行う必要がございます。

リダイレクト型の場合、ライブラリはサブウィンドウ型と違いトークンの作成のみを行うため、 card.three_d_secure_status が unverified な状態のトークンが返ってきます。
その後、加盟店様の処理により 3Dセキュアに誘導、および認証の終了を検知して 3Dセキュア完了エンドポイントへリクエストをする必要があります。

3Dセキュアありの状態で作られたトークンは、3Dセキュアを完了させるの手順を完了するまでは支払いや顧客への登録に使用できない状態になります。

3Dセキュアに誘導する

3Dセキュアワークフローにリダイレクト型を指定してトークンを作成した後、3D セキュア認証を進めるためにエンドユーザーをカード会社が提供する 3D セキュア認証画面に誘導します。

利用者を下記のエンドポイントにリダイレクトさせます。

https://api.pay.jp/v1/tds/トークンID/start?publickey=....&back=...

リダイレクト時のパラメーターとして、完了後の戻り先となる URL を指定します。以下の 2 通りの指定ができます。

  • back
    • PAY.JP の管理画面で事前に登録した戻り先 URL を使用する場合に指定します。登録時に設定した識別子を指定してください。
  • back_url
    • 動的に戻り先 URL を指定する場合に使用します。JWS（JSON Web Signatures）形式のデータで、戻り先 URL を含めて指定します。 back_url を使用した実装はコードサンプルを参考にご実装ください。

エンドポイントとパラメーターの詳細はAPIリファレンス - 3Dセキュア開始をご覧ください。

処理完了、あるいはエラーとなったタイミングで、利用者は指定した戻り先 URL にリダイレクトされます。戻り先 URL では次項の 3Dセキュア完了処理を行います。

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

3Dセキュアを完了させる

カード発行会社における認証の終了を検知したら、3D セキュア完了エンドポイントに秘密鍵でリクエストします。

curl -X POST https://api.pay.jp/v1/tokens/トークンID/tds_finish \
-u sk_test_c62fade9d045b54cd76d7036:

3D セキュア認証が正しく行われていれば、カードの有効性確認が行われ、通常のトークン作成と同様のレスポンスが返却されます。

3D セキュアが成功 ( verified / attempted ) であっても、通常のトークン作成同様、カードの一時的な停止などの原因によって失敗レスポンスが返却される可能性もあります。

この手順が正常に完了すれば、得られたトークンを通常通り支払い作成や顧客に紐付けて使うことが可能となります。

より細やかな制御をする場合は、3Dセキュア完了エンドポイントにリクエストする前にトークンオブジェクトを取得し下記の項目のような実装をご検討ください。

完全認証を行いたい場合

取得されたトークンオブジェクトの card.three_d_secure_status が attempted の場合に購入手続きを中断することで、完全認証となります。それ以外にも、商品や金額等をふまえて加盟店独自の基準で制御することも可能です。

card.three_d_secure_status が失敗状態のとき

unverified のままであったり、error であったりする場合は、3D セキュアの手順中に離脱した、パラメーターに異常があった等の問題が考えられます。この状態では 3D セキュア完了エンドポイントへのリクエストもエラーとなるため、トークン作成から 3D セキュアフローをやり直す必要があります。
attempted または verified の場合は 3Dセキュア完了が可能です。