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

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

注意事項

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

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

3Dセキュア実装サンプル・デモ

実際にお手元で動作するサンプルをご用意しております。

掲載箇所 リンク
GitHub https://github.com/payjp/payjp-php-tds-sample
ドキュメント 3Dセキュアフロー実装サンプル・デモ

3Dセキュアを開始する

それぞれのクライアントライブラリで特定のオプションを指定することで、トークン作成時に 3Dセキュアを開始できます。
また、3Dセキュアを行うためのテストカードはありません。
このオプションを指定することで、すべてのテストカードで 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セキュアワークフローを指定する必要があります。
サービス形態や実装にあわせて適切なものをご指定ください。		 
<script
    type="text/javascript"
    src="https://checkout.pay.jp/prerelease"
    class="payjp-button"
    data-payjp-key="`pk_` から始まる公開鍵を設定してください。"
    data-payjp-three-d-secure="true"
    data-payjp-three-d-secure-workflow="subwindow"
    data-payjp-extra-attribute-email
    data-payjp-extra-attribute-phone
></script>

●payjp.jsでの開始方法

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

const payjp = Payjp(
    '`pk_` から始まる公開鍵を設定してください。',
    { threeDSecureWorkflow: 'subwindow' } // 3Dセキュアワークフローを指定する場合
)
// elemennt の mount などは省略
payjp.createToken(cardElement, {
  three_d_secure: true,
  // 3D セキュアを行う場合、カードホルダーの名義および、メールアドレス・電話番号のどちらかの入力が求められますのでご注意ください。
  card: { name: 'PAY JP', email: 'liveaccount@example.com', phone: '+81301234567' },
}).then((response) => {
  if (response.error) {
    // エラー処理
  } else {
    // response.id はトークンの ID
  }
}).catch((error) => {
    // 一般的なエラーハンドリング(payjs内からのrejectはErrorオブジェクト)
})

詳細な仕様についてはリファレンスにもございますので、そちらもあわせてご確認ください。

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

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

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

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

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

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

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

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

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

●Checkout

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

<script
    type="text/javascript"
    src="https://checkout.pay.jp/prerelease"
    class="payjp-button"
    data-payjp-key="`pk_` から始まる公開鍵を設定してください。"
    data-payjp-three-d-secure="true"
    data-payjp-three-d-secure-workflow="subwindow"
    data-payjp-extra-attribute-email
    data-payjp-extra-attribute-phone
></script>

●payjp.js

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

  • card.name
  • card.phone または card.email のいずれか
<!-- 追加項目の入力フォームを用意します。 -->
<input type="text" id="name">
<input type="text" id="email">
<input type="text" id="phone">
<script>
  // payjp のインスタンス化や element の mount などは省略
  const name = document.getElementById('name').value;
  const email = document.getElementById('email').value;
  const phone = document.getElementById('phone').value;
  payjp.createToken(cardElement, {
    three_d_secure: true,
    card: {
      name: name,
      email: email,
      phone: phone,
    },
  }).then(/* 省略 */).catch(/* 省略 */);
</script>

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

●モバイル 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 を渡します。

サブウィンドウ型

サブウィンドウ型の概要についてはPAY.JP における 3D セキュア - ●サブウィンドウ型をご覧ください。

サブウィンドウ型では、トークン作成と同時にライブラリが認証処理を実施します。
そのため、作成されたトークンは通常通り作成が完了したものと同じ状態で、かつ 3D セキュアの実施が完了した状態で戻ってきます。

サブウィンドウ型での注意事項

下記に列挙するような環境ではポップアップに対して警告やブロックが働くため、3Dセキュアが行えない場合がございます。
それを踏まえた上でご利用いただくか、リダイレクト型での実装をご検討ください。

1. ポップアップブロック

ブラウザごとのデフォルト値やユーザー設定によって、ポップアップブロック機能が有効化されている場合があります。
そのような環境からサブウィンドウ型での 3Dセキュア認証を実行しようとした場合、サブウィンドウの起動がブロックされ認証ができません。
サブウィンドウ型をそのような環境の利用者に使ってもらうには下記の対応が考えられます。


  1. ポップアップブロック機能を無効化してからカード情報を入力してもらう
  2. ポップアップがブロックされた際にブラウザ URL バー付近のポップアップブロック通知からポップアップを許可する

※ 2 で許可を選ぶとポップアップまたは新規タブにおいて、カード会社による 3Dセキュア認証画面が現れますが、ブロックされた時点でその認証は無効となります。
その場合再度カード情報の入力からやり直してください。

上記が難しい場合、リダイレクト型に切り替える必要があります。

2. Cross-Origin-Opener-Policyヘッダー

加盟店様サイト側でレスポンスヘッダーに Cross-Origin-Opener-Policy を設定している場合にサブウィンドの起動がブロックされる場合があります。
この場合はサイト側のヘッダー設定を変更していただくか、リダイレクト型に切り替える必要があります。

3. モバイルアプリブラウザ

モバイルアプリ内のブラウザはその中で別タブを開いたりといった機能に基本的に対応していません。
そのためサブウィンドウ型は動作しませんので、モバイル SDKのご利用をご検討いただくか、リダイレクト型に切り替える必要があります。

リダイレクト型

リダイレクト型の概要についてはPAY.JP における 3D セキュア - ●リダイレクト型をご覧ください。

リダイレクト型では、 ライブラリはトークン作成のみを行うためその後の3Dセキュア認証処理は加盟店様側で実装する必要がございます。

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

3Dセキュアに誘導する

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

3Dセキュア開始エンドポイントへエンドユーザーを誘導する際の詳細な仕様については APIリファレンス - 3Dセキュア開始 をご覧ください。

実際にお手元で動作するサンプルをご用意しております。

掲載箇所 リンク
GitHub https://github.com/payjp/payjp-php-tds-sample
ドキュメント 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セキュア完了が可能です。