PAY.JP
3Dセキュア導入方法
これは PAY.JP API v1 のドキュメントです。v2 のドキュメントはこちら、v1 からの移行は移行ガイドをご覧ください。

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

トークン作成時に 3Dセキュア認証を行う

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

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/"
    class="payjp-button"
    data-payjp-key="`pk_` から始まる公開鍵を設定してください。"
    data-payjp-three-d-secure="true"
    data-payjp-three-d-secure-workflow="iframe"
    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: 'iframe' } // 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/"
    class="payjp-button"
    data-payjp-key="`pk_` から始まる公開鍵を設定してください。"
    data-payjp-three-d-secure="true"
    data-payjp-three-d-secure-workflow="iframe"
    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.jsiframe型 Payjp インスタンスの初期化時のoptionsに { threeDSecureWorkflow: 'iframe' } を渡します。
payjp.jsリダイレクト型 Payjp インスタンスの初期化時のoptionsに { threeDSecureWorkflow: 'redirect' } を渡します。
payjp.jsサブウィンドウ型特に指定しない場合、デフォルトでサブウィンドウ型となります。
Checkoutiframe型Checkout - 属性の data-payjp-three-d-secure-workflow に iframe を渡します。
Checkoutリダイレクト型Checkout - 属性の data-payjp-three-d-secure-workflow に redirect を渡します。
Checkoutサブウィンドウ型Checkout - 属性の data-payjp-three-d-secure-workflow に subwindow を渡します。

iframe型

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

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

リダイレクト型

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

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

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

3Dセキュアに誘導する

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

3Dセキュア開始エンドポイントへエンドユーザーを誘導する際の詳細な仕様については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セキュア完了が可能です。

サブウィンドウ型

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


※サブウィンドウ型を導入するよりも iframe 型を組み込んだ方が多くの環境で動作可能となりますので、まずそちらの使用を先にご検討ください。
これからサブウィンドウ型を組み込む場合、注意事項をよく読んだ上でご利用いただけますようお願いいたします。

サブウィンドウ型は処理がサブウィンドウ内で行われること以外ほぼ iframe 型と挙動や実装方法が同じです。
ワークフローの指定方法の通りサブウィンドウ型を指定することにより切り替えることができます。