本ガイドの内容

本ガイドは、（株）DGフィナンシャルテクノロジーが提供するVeriTrans4Gの本人認証サービス（3Dセキュア2.0）をECサイトに導入するための、アプリケーション開発者向けのガイドです。

本ページと併せて「本人認証サービス補足資料（3Dセキュア2.0対応版）」もご確認ください。

本人認証サービス（3Dセキュア2.0）について

本人認証サービスはクレジットカード決済と連動する3Dセキュアによる認証サービスです。

3Dセキュア2.0は、EMVCoが中心となって策定された本人認証サービスの総称で、クレジットカードブランドごとにサービスの名称が異なります。

• Visa Secure　（旧VISA認証サービス）
• Mastercard ID Check(TM)
• JCB J/Secure(TM)
• American Express SafeKey(R)
• Diners Club ProtectBuy(R)

ブランドのサービス名称は変更となる場合があります（上記は2022年2月現在）。

3DセキュアバージョンアップによるVeriTrans4G本人認証サービスへの影響

本資料は3Dセキュア2.0に対応した資料となります。以前のバージョン（3Dセキュア1.0）と用語が異なる箇所があります。
3Dセキュア1.0では、加盟店（ECサイト）側で3Dセキュア認証を処理する部分（機能）を「MPI（Merchant Plug-In）」と呼びますが、3Dセキュア2.0ではMPIという表現は用いられません。3Dセキュア1.0における「MPI」は、3Dセキュア2.0では「3DSサーバー」となります。

そのため、厳密には「MPIホスティング」という表現は、3Dセキュア2.0では適切でない表現となりますが、「3Dセキュア認証サービス（1.0か2.0に限らず）」と「MPIホスティングサービス」は同等の機能（サービス）として扱っても大きな問題はありません。

なお、2022年2月時点でVeriTrans4G本人認証サービスは、3Dセキュア2.0の「ブラウザベース認証」に対応しています。「アプリベース認証」には対応していません。

機能一覧（決済要求コマンド）

使用可能な決済要求コマンドを下表に示します。

• 3Dセキュアの処理フローでは、認可の成功後、消費者のブラウザをカード会社のサイトに遷移させることで認証が行われます。その後、決済サーバーが認証結果の判定（検証）を実施し、判定結果と認証タイプ（本書では「決済サービスオプションタイプ」）を元にカード決済（与信）の実行に進みます。

決済処理シーケンス

（重要）

• 【2．リダイレクト指示】でresResponseContentsを利用する場合は、決済サーバーから受信した resResponseContents を加工・編集せずに、そのままブラウザに送信してください。加工・編集を加えた場合、認証処理が正しく動作しない可能性があります。
• 【3．結果通知（PUSH通知）】と【４．結果連携】は非同期で実行されます。どちらを先に受信しても処理できるように実装してください。
  結果の取得方法の詳細は「4-4本人認証およびカード決済の結果取得」を参照して下さい。

基本項目について

• 「設定」欄の内容は以下の通りです。

  要求電文 ...

  必須項目：○　　任意項目：△　　設定不可：×　　その他条件付：※、※n（条件は説明欄、または欄外に記入）

  応答電文 ...

  必ず返戻：○　　処理成功時のみ返戻：△　　返戻なし：×　　その他条件付：※

• orderId（取引ID）について

  店舗で任意に採番してください。申込処理毎に付ける必要があります。他の取引IDと重複しないよう採番してください。他決済サービスとも重複できません。
  また、テスト取引で使用した取引IDを、本番取引で再度使用することはできません。
  取引IDには、半角英数字以外に"-"（ハイフン）、"_"（アンダースコア）も使用可能です。

• 応答電文について

  応答電文には、本書に記載されていないフィールド（パラメータ）も存在しますが、通常は、記載されているフィールド以外は加盟店様の方で意識する必要はございません。

特記事項

本人認証要求

本人認証およびカード決済の結果取得

本人認証およびカード決済の結果は、以下の4通りの方法で取得することができます。

• ①はブラウザを経由した結果連携のため、画面遷移が正常に行われないケースでは結果を取得することができません。そのため、②の結果通知の受信と組み合わせて確実に結果を取得するようにしてください。
• ③と④は、取引ID等のキーとなるパラメータを条件に指定した問合せ型のコマンドになります。
  • その他の方法と組み合わせて利用されることを想定しています。

結果通知

決済サーバーは、本人認証、およびクレジットカード決済の結果を加盟店サイトへ通知します。
尚、本人認証結果の検証後（連動してクレジットカード決済が実行される場合は決済実行後）に、決済成否に関わらず通知します。
結果通知に関するサービス共通の仕様については、『開発ガイド』を併せてご参照ください。

検索

• 「設定」欄の内容は以下の通りとなります。

  要求電文 ...

  必須項目：○　　任意項目：△　　設定不可：×　　その他条件付：※（条件は説明欄に記入）

  応答電文 ...

  必ず返戻：○　　該当取引存在時に返戻：△　　返戻なし：×　　その他条件付：※

• 複数指定は0～の添字を指定します。

  例）exparam.serviceTypeCd[0]=card&exparam.serviceTypeCd[1]=mpi

• ワイルドカードは値の一部と"*"を組み合わせて検索します。"*"のみの指定はできません。

  例）exparam.searchParameters.common.orderId=123*

決済サービスオプションタイプについて

VeriTrans4G本人認証サービスでは、3Dセキュア認証の結果をもとにクレジットカード与信（カード与信）処理まで実施可能です。
カード与信を実施するかしないかの判定ルールは、「決済サービスオプションタイプ（serviceOptionType）」に指定する値によって異なります。

1. mpi-complete（完全認証）

   カード会社が認証成功と判定した場合のみ、カード与信を実施します。

2. mpi-company（通常認証）

   カード会社が認証成功　または　みなし認証成功（Attempt）と判定した場合、カード与信を実施します。

3. mpi-merchant（通常認証：加盟店リスクあり）

   できる限りカード与信を実施するモードになります。加盟店様が3Dセキュアのご利用契約をされていないブランドのカード、処理中にエラーが発生した場合でも加盟店リスク負担でカード与信を実施します。ただし、3Dセキュア認証処理が正常に行われ、明確にNG（ステータスN受信ケースなど）の場合、カード与信は行いません。

4. mpi-none（単体認証）

   本人認証（3Dセキュア認証）のみを実施し、カード与信は実施しません。カード与信を実施するかの判断とカード与信の処理（リクエスト）は加盟店様で行う必要があります。カード与信を実施するかの判断方法はmpi-none 以外のモードの判定を参考に実装してください。カード与信はCardAuthorizeRequestDtoを使用します。「MPI（3Dセキュア）の結果を連携する場合に使用するフィールド」に本人認証の結果を設定してください。詳しくは、クレジットカード決済のインターフェース詳細をご参照ください。

mpi-noneは、3Dセキュア認証とカード決済の処理を分けて実行できるため、カード決済の与信を加盟店様のタイミングで実行したい場合に利用されるケースが多いです。また、何等かの理由で弊社からの結果通知を受信できない場合にも利用されることがあります。
しかし、mpi-noneの場合は、与信を実行するか否かの判定を加盟店様のシステムで実装する必要があり、また、与信の要求時には3Dセキュアの認証結果を正確に設定しなければチャージバックリスクとなるため、少し難易度が高いです。
mpi-none以外を利用する場合は、弊社側でこれらの処理を行いますのでその点では難易度は低いです。しかし、結果通知を必ず受信していただく必要があります。

※結果通知を受信しないと、決済の成立を加盟店側で検知できないことがあり、お客様が支払ったのに注文が成立しなかったり、注文が不成立のため、再度お客様が決済を実行して2重決済となるなど、クレームに発展するリスクがあります。

決済サービスオプションタイプ別の結果の判定方法の詳細については、「本人認証サービス補足資料（3Dセキュア2.0版）」の「2 決済サービスオプションタイプについて」「5-3 結果判定マトリックス」を参照してください。

決済結果の判定について

本人認証サービスでは、決済サービスオプションタイプ（serviceOptionType）が"mpi-none"である場合を除き、本人認証の成功時（みなし成功を含む）には、カード決済が実行されます。
加盟店サイトでは、必ずカード決済が成功したことをご確認のうえ、商品の発送やサービスのご提供を行うようにしてください。
カード決済が成功した場合の結果コードの例を以下に示します。

以下は、本人認証は成功、カード決済は失敗の例です。

決済サーバーと加盟店サイト間の取引不整合の問題

本人認証およびカード決済の成功後、消費者のブラウザから加盟店サイトの完了画面に遷移しなかった場合、あるいは遷移に失敗して処理の途中で離脱した場合には、加盟店サイトではカード決済の成立を認識できないという問題が発生する場合があります（取引不整合）。この問題は、以下のような状況で発生する可能性があります。

• カード会社の本人認証画面（パスワード入力画面）で長時間滞留したため、加盟店サイトでセッションタイムアウト（注文の期限切れ等）が発生したことによって、決済結果の反映処理が行えなかった場合
• 本人認証の成功後にブラウザを閉じる等の操作を行った

この問題に対処するために、加盟店サイトでは以下の何れかの実装を行って頂きますようお願いいたします。

1. 決済サーバーからの決済結果通知（PUSH）を受信する （「5-5 結果通知の送信（Push）」 をご参照ください）
2. 本人認証結果確認コマンドで、決済が成立していないかどうかを確認する
3. 未成立の取引をSearchコマンドで検索し、決済が成立していないかどうかを確認する（新規に実装される場合、非推奨。②本人認証結果確認コマンドをご利用ください）

なお、Searchコマンドをご利用の場合は、必ず 「5-2 決済結果の判定について」 を参考に、「カード決済が成功しているかどうか」をご確認ください。

決済結果の詳細パラメータ連携とGETによるリダイレクションURIへのアクセス

消費者のブラウザを経由して送信する認証結果およびカード決済の結果は、HTTPのPOSTメソッドで送信しています。そのため、各種ブラウザの仕様変更に伴う、CookieのSameSite属性の挙動変更の影響には注意が必要です。
VeriTrans4Gでは、3Dセキュア2.0への対応に合わせて、リダイレクションURIに遷移する際にHTTP GETで遷移できるようにするフラグを用意しましたので、POSTメソッドでの遷移に問題がある場合にはこのフラグの利用をご検討ください。

• 「4.3.1 認可」の「詳細パラメータ連携フラグ（verifyResultLink）」で、2を指定するとHTTP GETで遷移します。

  0:詳細パラメータ連携しない

  （キー情報のみPOSTで送信）

  1:詳細パラメータ連携する（POST）

  （キー情報と結果すべてをPOSTで送信）

  2:詳細パラメータ連携しない（GET）

  （キー情報のみGETで送信）

ただし、HTTP GETによる遷移の場合、クエリパラメータにはキー情報のフィールド（「取引ID」と「リクエストID」）のみが設定されますので、別途、キー情報を利用して認証および決済の結果を問い合わせる必要があります。詳しくは、「4-4 本人認証およびカード決済の結果取得」をご参照ください。

• HTTP GETによる遷移は、ブラウザの再読み込み（リロード）操作により、同じリクエストが複数回届くケースが発生いたしますので、同じリクエストが届いても問題ないように実装してください。（HTTP POSTによる実装の場合、再読み込みを行った場合はリクエストからパラメータが取得できないため、動作として問題となっていない可能性もあります。）
• 従来の仕様では、詳細パラメータ連携の有効・無効の切り替えは、決済サーバーのマスタ設定を弊社で変更するしかありませんでしたが、verifyResultLinkフラグによる制御を優先するようになり、加盟店様の実装にて切り替えが可能となりましたので、フラグによる切替を実装される加盟店様は、特にマスタ設定を意識する必要はありません。
• 詳細パラメータ連携を有効にする場合、決済サービスオプションタイプ（serviceOptionType）でMPI単体サービス（"mpi-none"）を選択する場合は、リダイレクト先となる加盟店サイトの結果画面のURIはSSL(https://)を必須とします。ダミーモードでのテストも考慮し、HTTPのURIを指定した場合でもエラーにはなりませんのでご注意ください。

結果通知の送信（Push）

決済サーバーから加盟店サイトへ、本人認証結果、およびクレジットカード決済結果を送信（Push）する機能です。
本人認証サービスの決済フローは、加盟店サイトから一度外部サイトにブラウザ（クライアント）を遷移する形となっており、外部サイトにて決済処理を行い、またブラウザを経由して加盟店サイトに戻ります。
ブラウザを経由した遷移は、正しく行われない（リダイレクトが届かない）ケースは発生するものとしてご認識ください。
つまり、外部サイト（VeriTrans4G側）で本人認証の結果、クレジットカード与信処理が行われたが、その後、加盟店サイトに戻ってこない事象が発生し、加盟店サイトでは決済が完了していないという不整合が発生する可能性があります。

結果通知を受信することで、消費者が離脱してしまった場合でも、決済が行われたかどうかを加盟店サイトにて把握することが可能となります。 なお、結果通知は、クレジットカード決済の結果が失敗の場合も送信（PUSH）されます。

結果通知は、認可要求時のパラメータ、またはMAP（マーチャント管理ポータル）の「各種設定変更」より設定したURLに届きます。 なお、古いバージョンのMDKでは、認可要求時に通知先URLを指定できないものもございますが、3Dセキュア2.0対応のMDKでは指定可能となっております。 結果通知の受信処理については、『4G_開発ガイド』を参照してください。

本人認証処理の有効期限

本人認証有効期限（verifyTimeout）の設定により、本人認証の画面で長時間滞留する等、認証完了までに時間がかかった取引を無効（タイムアウトエラー）にすることができます。
例えば、加盟店サイトのセッションタイムアウトが30分の場合は、verifyTimeout値を30分よりも短く設定することで、決済サーバー側で決済が成立しているのにもかかわらず、加盟店サイトに戻ったときにセッションタイムアウトエラーになる、という問題を回避することができます。

3Dセキュア2.0のフローでタイムアウトがチェックされるのは次の2つのタイミングとなります。

1. 検証処理開始時（AReq送信前）
2. RReq受信時

• 処理フローについては、「本人認証サービス補足資料（3Dセキュア2.0版）」 を参照してください。
• タイムアウト判定の起点は、厳密には決済サーバーの認可処理の完了時間に近いタイミングとなり、加盟店サイトからリクエストを送信したタイミングが起点ではないためご注意ください。

1.のタイミングでタイムアウトした場合は、決済サーバーはAReq送信を行わず、MPI処理結果失敗（mpiMstatus=failure）でリダイレクションURIに遷移が戻るフローとなります。

• verifyTimeout値は分単位の設定のため、1.のタイミングでタイムアウトする可能性は高くはありません。

2.のタイミングでタイムアウトした場合は、RReqの内容が認証可（オーソリ可）の場合でも決済サーバーはオーソリを行わず、MPI処理結果失敗（mpiMstatus=failure）でリダイレクションURIに遷移が戻るフローとなります。

タイムアウト発生時の結果コードは3Dセキュア1.0と変わりません。

消費者様より当エラーに関する問合せがあった場合は、「タイムアウトエラーのため注文をやり直していただく必要がある」ことをご案内ください。

本人認証有効期限を設定しなければ、有効期限の判定は行われません。この場合、弊社サービス上のタイムアウトは発生しないため、消費者のブラウザ操作のタイミング次第で、長時間経過後に決済が成立することがあります。

検索（Search）に関する補足

決済サーバーは、取引ID毎の内部処理（トランザクション）の履歴と現在の決済状態を保持しています。
Search コマンドでは決済サーバーが保持しているトランザクション情報を取得することが可能ですが、各トランザクションの種類は「トランザクションタイプ」で表されます。
下表に3Dセキュアおよびカード決済の主なトランザクションタイプを示します。

注） 一覧に記載していないタイプも存在します。

• 取引の状態確認が必要な場合には、Searchの結果からorderInfo.successDetailTxnType（詳細トランザクションタイプ）を参照することで、現在の決済状態を確認できます。ただし、orderInfo.successDetailTxnTypeには「直前に成功したトランザクションのタイプ」が設定される仕様のため、その後の処理が失敗したことを明確に示すことはできません。
  

  例）

  " successDetailTxnType ": "a"

  ⇐ 与信が成功した状態であることを示します。

  " successDetailTxnType ": "vpa"

  ⇐ 売上の取消が成功した状態であることを示します。

• 取引ID毎のSearchの結果には、3Dセキュアの認証結果とカード決済の結果が含まれます。カード決済の結果詳細を確認するには、カード決済のトランザクション情報（transactionInfo）を参照してください。トランザクション情報の種類は、properTransactionInfo.txnKind（トランザクション種類）で識別できます。

  "txnKind": "mpi"

  ⇐ 3Dセキュアのトランザクション情報であることを示します。

  "txnKind": "card"

  ⇐ カード決済のトランザクション情報であることを示します。