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

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

注意事項

現在下記機能が開発中となっております。

  • Checkoutでのトークン作成時の3Dセキュア機能
  • Checkoutでの追加項目入力機能
  • トークン3Dセキュアの実施要否をパラメーターで指定する機能(現在 payjp.js・モバイル SDK のみ対応)

3Dセキュアを開始する

管理画面 > API設定 > 3Dセキュア よりトークン3Dセキュアの実施モードを指定することで、全てのトークン作成に3Dセキュアを必須とすることができます。
管理画面より有効化後、通常通りトークンを作成することで3Dセキュア処理待ち状態のトークンが作成されます。
3Dセキュア処理待ち状態のトークンは card.three_d_secure_status が unverified となっており、また3Dセキュアが完了するまで支払い等に使えない状態となります。

トークン作成時に任意のタイミングで3Dセキュアを行う

管理画面で実施モードを設定する代わりに、トークン作成の際に追加のパラメーター three_d_secure=true を指定することで、全てではなく任意のタイミングでトークン作成時の3Dセキュアを開始することができます。
この機能は現在開発中となっており、payjp.js・モバイル SDK のみが対応しています。
各ライブラリのドキュメントをご参照の上でご指定ください。

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

追加項目に関してはPAY.JPにおける3Dセキュア - 3Dセキュア認証における追加項目をご覧ください。
トークン作成時の3Dセキュアを行う場合、カード情報と共にメールアドレス・電話番号のどちらかを含めてエンドユーザーに入力してもらう必要があります。
お使いのクライアントライブラリに合わせて、設定をご確認ください。

payjp.js

追加項目をcreateToken関数のoptions引数に含める必要があります。
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 を渡します。

※Checkoutは現在機能開発中となっており、ご使用いただけません。

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

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

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

リダイレクト型について

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

リダイレクト型の場合、ライブラリはサブウィンドウ型と違いトークンの作成のみを行うため、 card.three_d_secure_status が unverified な状態のトークンが返ってきます。
その後、加盟店様の処理により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セキュア完了処理を行います。

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

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

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

3D セキュア認証が正しく行われていれば、カードの有効性確認が行われ、通常のトークン作成と同様のレスポンスが返却されます。
注意： 3D セキュアが成功だったとしても、通常のトークン作成同様、カードの一時的な停止などによりトークン作成が失敗し、失敗レスポンスが返却される可能性もあります。

こうして得られたトークンは、通常通り支払い作成や顧客に紐付けて使うことが可能となります。

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

完全認証を行いたい場合

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

card.three_d_secure_statusが失敗状態のとき

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