PAGuide.book

導入ガ イ ド

シ ン プル

API

サイバー ソ ースの連絡先

サイバー ソ ースの連絡先

http://www.cybersource.co.jp/ サ イ バー ソ ース株式会社の会社概要、 サービ ス の概要、FAQ な ど を用意 し てお り ます。 [email protected] ま たは 03-3548-9873 営業グループ サービ スや料金に関す る お問い合わせは こ ち ら ま で ど う ぞ。 http://www.cybersource.co.jp/supportcenter/ CyberSource サポー ト リ ン ク 一覧です。 [email protected] ま たは03-3548-9874 （サポー ト 直通） カ ス タ マーサポー ト 技術面に対す る お問い合わせは こ ち ら ま で ど う ぞ。 サ イ バー ソ ース株式会社 〒100-0004 東京都千代田区大手町2-1-1 tel: 03-3548-9873 （代表） fax: 03-3548-9872

こ の文書について

お こ と わ り

• 当社の同意無 く 本ガ イ ド の全部 ま たは一部の複写 ・ 複製 ・ 転載をす る こ と を固 く 禁 じ ます。 • 本ガ イ ド の内容は将来予告な し に更新 さ れ る こ と が ご ざい ますので、 ご留意下 さ い。 • 本ガ イ ド の記述内容については万全を期 し てお り ますが、 不備等、 お気づ き の点 がご ざい ま し た ら 、 お手数ですが上記の問い合わせ先ま で ご連絡下 さ い。

Copyright

Copyright (C) 2011 CyberSource K.K. All rights reserved.

(C)CyberSource Corporation. All rights reserved.CyberSource Corporation ( 以下、 「CyberSource」 ) は、 本ガ イ ド お よ び本ガ イ ド で説明する ソ フ ト ウ ェ ア を、 本ガ イ ド の 読者( 以下、 「お客様」 ) と CyberSource 間の所定の契約書 ( 以下、 「本契約書」 ) の下に 提供す る も の と し ます。 本ガ イ ド お よ び ソ フ ト ウ ェ アは、 本契約書の条項に従っ ての み使用す る こ と がで き ます。 本契約書で明示的に記述 さ れてい る 場合を除 き 、 本ガ イ ド に記載 さ れてい る 情報は、 予告な く 変更す る 場合があ る ため、CyberSource の一切の 保証を意味す る も のではあ り ません。CyberSource は、 本ガ イ ド に誤 り や不正確な記述 があ っ た場合に も 、 一切の責任を負い ま せん。 本ガ イ ド に付随す る 著作権のあ る ソ フ ト ウ ェ アは、 お客様が本契約書の条項を厳守す る 場合にのみ使用が許可 さ れ ます。 ソ フ ト ウ ェ ア を使用す る 前に、 必ず本契約書を慎重にお読み く だ さ い。 本契約書に よ り 許可 さ れてい る 場合を除 き 、 本ガ イ ド のいかな る 部分 も 、CyberSource の書面に よ る事 前の許可な し に、 電子的、 機械的、 録音、 その他いかな る 手段に よ っ て も 、 検索シ ス テ ムへの保存、 ま たは伝送を行 う こ と はで き ません。

商標

CyberSource、 the CyberSource logo、 SmartCert、 およ び PaylinX は、 米国 CyberSource の 米国 お よ び そ の 他 の 国 に お け る 登録 商標 で す。The Power of Payment、 CyberSource Payment Manager、 CyberSource Risk Manager、 CyberSource Decision Manager、 お よ び CyberSource Connect は、 米国 CyberSource Corporation の商標ま たはサービ ス マー ク で す。 その他の会社名ま たは製品名は、 それぞれの会社の商標ま たは登録商標です。

変更月 内容

December 2011 _{• J/Secure のテス ト カー ド が追加 さ れま し た}

November 2009 _{• Amex や Diners カー ド で Enroll リ ク エス ト を送信 し な} いで く だ さ い。 • 本人認証のテ ス ト に関する情報を追加 し ま し た • シ ン プルAPI および SCMP のフ ィ ール ド を ア ッ プデー ト し ま し た （ リ プ ラ イ フ ィ ール ド が追加 さ れま し た） July 2008 _{• シ ン プルAPI および SCMP のフ ィ ール ド を ア ッ プデー} ト し ま し た • 登録確認 と 与信を同時に リ ク エ ス ト し た場合に、 すべて のカ ー ド で登録確認の結果を与信に渡す こ と がで き る よ う にな り ま し た。 August 2007 _• 新規 リ リ ース

サ イ バー ソ ース の連絡先... ii こ の文書について... ii お こ と わ り... ii 変更履歴... iii Copyright... iii 商標... iii

第

1 章

は じ めに... 1 本人認証サービ ス の概要... 1 本人認証のプ ロ セ ス... 1 登録確認 と 本人認証... 1 検証... 3 与信 リ ク エ ス ト と の組み合わせ... 3 登録確認 と 同時に与信を リ ク エ ス ト ... 3 検証 と 同時に与信を リ ク エ ス ト ... 4 与信を別途 リ ク エ ス ト ... 4 本人認証サービ ス のオプシ ョ ン... 4 導入にあ た っ て... 5

第

2 章

シ ン プルAPI ... 7 API の紹介 ... 7 シ ン プルAPI ク ラ イ ア ン ト ... 7 API のバージ ョ ン ... 7 デー タ 型の定義... 7 日本語入力について... 8 ICS サービ スへのア ク セ ス ... 8 名前/ 値ペア及び XML の フ ィ ール ド 名の相関関係について ... 8 リ ク エ ス ト の作成 と リ プ ラ イ の解釈... 9 リ ク エ ス ト を構築す る... 9 リ プ ラ イ を解析す る... 10 判定... 10 理由 コ ー ド ... 11 欠けてい る ま たは無効な フ ィ ール ド ... 11 注文の追跡... 11 注文番号... 11 リ ク エ ス ト ID ... 12 リ ク エ ス ト ト ー ク ン... 12 本人認証サービ ス... 12 利用可能な アプ リ ケーシ ョ ン... 12 本人認証サービ ス で使われ る 識別子... 12 登録確認 （Enroll) ... 13 サービ ス の リ ク エ ス ト ... 13 リ プ ラ イ の解釈... 13 理由 コ ー ド ：475 ... 13 登録な し の場合にチ ャ ージバ ッ ク 保護を受け る ... 14 検証(Validate) ... 14 サービ ス の リ ク エ ス ト ... 15 リ プ ラ イ の解釈... 16 Visa 認証サービ ス ... 16 MasterCard SecureCode ... 17 J/Secure... 17 本人認証サービ スデー タ の保管... 17 サービ ス のテ ス ト... 18 API フ ィ ール ド ... 18

リ ク エ ス ト フ ィ ール ド... 18 リ プ ラ イ フ ィ ール ド... 20 理由 コ ー ド... 24

第

3 章

SCMP API...27 API について... 27 デー タ 型の定義... 27 日本語入力について... 27 リ ク エ ス ト の作成 と リ プ ラ イ の解釈... 27 リ ク エ ス ト... 27 リ プ ラ イ （返信）... 28 処理結果... 28 リ プ ラ イ フ ィ ール ド... 28 注文の追跡... 29 注文番号... 29 リ ク エ ス ト ID ... 30 リ ク エ ス ト ト ー ク ン... 30 本人認証サービ ス... 30 利用可能な アプ リ ケーシ ョ ン... 30 本人認証サービ ス で使われ る 識別子... 30 登録確認 （Enroll)... 31 サービ ス の リ ク エ ス ト... 31 リ プ ラ イ の解釈... 31 リ プ ラ イ フ ラ グ ：DAUTHENTICATE ... 31 リ プ ラ イ フ ラ グ ：SOK... 31 登録な し の場合にチ ャ ージバ ッ ク 保護を受け る... 32 検証(Validate)... 32 サービ ス の リ ク エ ス ト... 32 リ プ ラ イ の解釈... 33 Visa 認証サービ ス ... 34 MasterCard SecureCode... 34 J/Secure ... 35 本人認証サービ スデー タ の保管... 35 サービ ス のテ ス ト... 35 API フ ィ ール ド ... 35 リ ク エ ス ト フ ィ ール ド... 36 オ フ ァ ーフ ィ ール ド... 37 リ プ ラ イ フ ィ ール ド... 38 リ プ ラ イ フ ラ グ... 43

第

4 章

本人認証サービ スのテ ス ト...45 基本事項... 45 テ ス ト 用 ク レ ジ ッ ト カー ド 番号... 45 本人認証画面... 45 フ ィ ール ド 名対照表... 45 登録確認... 46 検証... 46 テ ス ト カー ド 番号... 47 Verified by Visa ... 47 登録あ り ： 認証成功... 47 登録あ り ：PARes が無効... 48 登録あ り ：Attempt... 48 登録あ り ： 認証が完了 し ていない （ イ シ ュ アが認証を実行で き ない等）... 49 登録あ り ： 認証失敗... 49 登録あ り ： 検証エ ラ ー （PARes 処理中にエ ラ ーが発生）... 50 登録確認エ ラ ー... 50 登録な し... 50 MasterCard SecureCode... 51 登録あ り ： 認証成功... 51 登録あ り ：PARes が無効... 51 登録あ り ：Attempt... 52

登録な し ... 54 J/Secure ... 54 登録あ り ： 認証成功... 54 登録あ り ： 認証が完了 し ていない （ イ シ ュ アが認証を実行で き ない等）... 55 登録あ り ： 認証失敗... 55

Appendix A

チ ャ ージバ ッ ク 保護の概要... 57 チ ャ ージバ ッ ク 保護について... 57 チ ャ ージバ ッ ク 保護が受け ら れ る 場合... 57 チ ャ ージバ ッ ク 保護を受け る ための条件... 58 用語説明... 58

Appendix C

サン プルデー タ ... 62 PARes... 62 ProofXML ... 63

Appendix D

リ ク エ ス ト と リ プ ラ イのサン プル... 66 シ ン プルAPI ... 67 名前/ 値ペア ... 67 登録確認 リ ク エ ス ト ... 67 登録確認 リ プ ラ イ （登録あ り ）... 67 登録確認 リ プ ラ イ （登録な し ）... 67 Visa 認証サービ ス ... 68 MasterCard SecureCode ... 68 J/Secure... 68 検証 リ ク エ ス ト ... 68 検証 リ プ ラ イ （本人認証成功）... 68 Visa 認証サービ ス ... 69 検証 リ プ ラ イ （本人認証失敗）... 69 MasterCard SecureCode ... 69 検証 リ プ ラ イ （Attempt） ... 69 J/Secure... 70 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （認証成功） ... 70 Visa 認証サービ ス ... 70 MasterCard SecureCode ... 71 J/Secure... 71 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （Attempt） ... 71 Visa 認証サービ ス ... 71 J/Secure... 72 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （登録な し ） ... 72 Visa 認証サービ ス ... 72 MasterCard SecureCode ... 72 J/Secure... 72 XML... 73 登録確認 リ ク エ ス ト ... 73 登録確認 リ プ ラ イ （登録あ り ）... 74 登録確認 リ プ ラ イ （登録な し ）... 74 Visa 認証サービ ス ... 74 MasterCard SecureCode ... 75 J/Secure... 75 検証 リ ク エ ス ト ... 75 検証 リ プ ラ イ （本人認証成功）... 76 MasterCard SecureCode ... 76 検証 リ プ ラ イ （本人認証失敗）... 76 J/Secure... 77

検証 リ プ ラ イ （Attempt）... 77 Visa 認証サービ ス ... 77 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （認証成功）... 78 Visa 認証サービ ス ... 78 MasterCard SecureCode... 79 J/Secure ... 79 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （Attempt）... 79 Visa 認証サービ ス ... 79 J/Secure ... 80 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （登録な し ）... 80 Visa 認証サービ ス ... 80 MasterCard SecureCode... 81 J/Secure ... 81 SCMP API ... 82 登録確認 リ ク エ ス ト... 82 登録確認 リ プ ラ イ （登録あ り ）... 82 登録確認 リ プ ラ イ （登録な し ）... 82 Visa 認証サービ ス ... 83 MasterCard SecureCode... 83 J/Secure ... 83 検証 リ ク エ ス ト... 83 検証 リ プ ラ イ （本人認証成功）... 84 MasterCard SecureCode... 84 検証 リ プ ラ イ （本人認証失敗）... 84 Visa 認証サービ ス ... 84 検証 リ プ ラ イ （Attempt）... 84 J/Secure ... 85 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （認証成功）... 85 Visa 認証サービ ス ... 85 MasterCard SecureCode... 86 J/Secure ... 86 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （Attempt）... 86 Visa 認証サービ ス ... 86 J/Secure ... 87 ク レ ジ ッ ト カー ド 決済 与信 リ ク エ ス ト （登録な し ）... 87 Visa 認証サービ ス ... 87 MasterCard SecureCode... 87 J/Secure ... 87

は じ めに

本章では、 サ イ バー ソ ース 本人認証サービ ス について説明 し ます。

サ イ バー ソ ース 本人認証サービ スは、EC( 電子商取引 ) バ ッ ク オ フ ィ ス業務に対する複 合的な ソ リ ュ ーシ ョ ン であ る 、ICS (Internet Commerce SuiteSM) の一部です。ICS サービ ス には こ の他に、 ク レ ジ ッ ト カー ド 決済、 ク レ ジ ッ ト カー ド 不正取引チ ェ ッ ク 、 デジ タ ルデ リ バ リ 、 ス ト ア ド ・ バ リ ュ ー、 サブ ス ク リ プシ ョ ンがあ り ます。 サ イ バー ソ ース は管理用サ イ ト と し て、 サ イ バー ソ ース ビ ジネ ス セン ターを用意 し て い ます。 ビ ジネ ス セ ン タ ーは、 ト ラ ンザ ク シ ョ ン検索、 レ ポー ト 機能、 ユーザ管理な ど の各種機能に加え てサ イ バー ソ ー ス の提供す る 様々なサービ ス の統合的なサポー ト 機 能を備え てい ます。

本人認証サービ スの概要

サ イ バー ソ ー ス 本人認証サービ ス を利用す る こ と で、Visa の Verified by VisaSM （Visa 認証サービ ス )、 MasterCard の MasterCard® SecureCode™、 JCB の J/SecureTMのカー ド ブ ラ ン ド 三社が提供す る 各本人認証サービ ス を一括 し て ご利用いただけ ます。本人認証 サービ ス を採用す る こ と に よ っ て、不正なオ ン ラ イ ン取引か ら 生 じ る チ ャ ージバ ッ ク の リ ス ク の低減が可能にな り ます。 本人認証サービ ス は次の よ う な ス テ ッ プで処理 さ れ ます。本人認証サービ ス の流れにつ いては本人認証のプ ロ セスで詳 し く 説明 し てい ます。 1 サ イ バー ソ ース にユーザ （ ク レ ジ ッ ト カー ド 会員） が本人認証プ ロ グ ラ ム に登録 し てい る か ど う か をチ ェ ッ ク す る 登録確認(Enroll) サービ ス を リ ク エ ス ト し ます。 2 ユーザが本人認証プ ロ グ ラ ム に登録済みの場合には、ユーザは自身の保有す る カー ド の カー ド 発行会社が用意す る 本人認証ページ上でパ ス ワ ー ド を入力 し て本人認 証を受け ます。 3 本人認証の結果を確認す る ための検証(Validiate) サービ ス を リ ク エ ス ト し ます。 4 本人認証サービ ス の結果を ク レ ジ ッ ト カー ド の与信 リ ク エ ス ト に加え て送信 し ま す。

本人認証のプ ロ セス

こ こ では、 本人認証サービ ス の処理の流れについて説明 し ます。登録確認 と 本人認証で はユーザ （ ク レ ジ ッ ト カー ド 会員） の本人認証プ ロ グ ラ ムへの登録の有無の確認か ら 、 実際にユーザが本人認証を行 う 部分について ま で を、検証では本人認証で得た PARes の処理について説明 し てい ま す。 実際にマーチ ャ ン ト サ イ ト への本サービ ス 導入にあ た っ ての情報及び受領す る 値については導入にあた っ てを参照 し て く だ さ い。

登録確認 と 本人認証

サ イ バー ソ ース の登録確認サービ ス は、 ユーザがVisa、 MasterCard、 JCB の提供する い ずれかの本人認証プ ロ グ ラ ムに登録 さ れてい る か ど う か を確認 し 、プ ロ グ ラ ムへの登録 が確認で き た場合にPAReq を作成 し ます。

本人認証サービ スの概要 図 1 登録確認 と 本人認証のプ ロ セス 1 ユーザがマーチ ャ ン ト サ イ ト で商品を カー ト に入れ、 チ ェ ッ ク ア ウ ト す る 際に購 買情報を記入 し ます。 マーチ ャ ン ト サ イ ト のシ ス テ ム はそ こ か ら 必要な情報を抽 出 し ます。 2 ユーザのカー ド がVisa、 MasterCard、 JCB の場合には、 本人認証プ ロ グ ラ ムに登録 し て い る か ど う か を 確認す る た め、 サ イ バー ソ ー ス に 対 し 登録確認サ ー ビ ス (Enroll) リ ク エ ス ト を送信 し ます。 3 サ イ バー ソ ース はVisa、 MasterCard、 JCB の各デ ィ レ ク ト リ サーバに、 ユーザのプ ロ グ ラ ムへの登録の有無を問い合わせます。 4 各デ ィ レ ク ト リ サーバは、 ユーザの登録の有無について カー ド 発行会社に問い合 わせます。

Note 実際には Attempt と い う 機能があ り 、 現在ほ と んどの Visa カー ド と 一部の JCB カー ド は 「登録あ り 」 と い う レ ス ポン ス を受け取る こ と にな り ます。 Attempt についてはApppendix A チ ャ ージバ ッ ク保護についてを参照 し て く だ さ い。 5 サ イ バー ソ ー ス はデ ィ レ ク ト リ サーバか ら の レ ス ポ ン ス を受け、 マーチ ャ ン ト に 対 し 以下のいずれか を登録確認の結果 と し て返 し ます。 登録が確認 さ れた場合。 マーチ ャ ン ト サーバでは以下の値を受信 し ます。 • こ の ト ラ ンザ ク シ ョ ン に付与 さ れたXID を含む PAReq

• PAReq の送付先であ る ACS （Access Control Server、 カー ド 発行会社が用意す る 本人認証サーバ） のURL。 登録が確認 さ れなか っ た場合。 本人認証のプ ロ セ ス には進 ま ず、 通常の与信処理 に進みます。 Note 「登録な し 」 の場合で も 、 多 く の場合はチ ャ ージバ ッ ク 保護を受け る こ と が 可能です。その場合には与信に必要な情報を添付 し て送信す る 必要があ り ます。詳 し く は登録な し の場合にチ ャ ージバ ッ ク 保護を受け る （シ ン プル API） ま たは登 録な し の場合にチ ャ ージバ ッ ク保護を受け る （SCMP) を参照 し て く だ さ い。 6 ユーザのカー ド の登録が確認 さ れた場合には、 PAReq をセ ッ ト し た認証 リ ク エ ス ト を カー ド 発行会社のACS に送信 し ます。 ユーザ マーチ ャ ン ト サーバ サ イ バー ソ ース デ ィ レ ク ト リ サーバ カー ド 発行会社_ACS 登録確認 登録確認 本人認証 8 6 7 5 4 3 2 1 PAReq ACS の URL PARes パ ス ワー ド 入力 PAReq

7 ユーザのブ ラ ウ ザにカー ド 発行会社の本人認証画面が表示 さ れ ま す。 ユーザは画 面に表示 さ れた メ ッ セージ を確認 し 、 本人認証用パ ス ワ ー ド を入力 し ます。 8 カー ド 発行会社は本人認証の結果を含むPARes をマーチ ャ ン ト サーバに返 し ます。

検証

PARes を受領 し た ら 、 次の段階の検証 （Validate) サービ ス に進みます。 検証サービ ス はカー ド 発行会社か ら 受領 し たPARes の電子署名を解析 し 、 正当な送 り 手 （ACS） か ら 受信 し た正当なデー タ で あ る こ と を検証 し ま す。 そ し て、 与信に添付すべ き 情報を 返 し ます。 図 2 検証のプ ロ セス 9 カー ド 発行会社か ら 受信 し た PARes をサ イ バー ソ ース に検証 リ ク エ ス ト と し て送 信 し ます。 10 マーチ ャ ン ト サーバは検証 リ ク エ ス ト の結果を受信 し ます。

11 PARes に含まれる XID が PAReq と 同 じ であ る こ と を確認 し ます。（一連の処理が同 一のカー ド に関 し て な さ れた こ と を確認 し ます。） 検証に成功 し た場合には、 リ プ ラ イ か ら 必要な情報を抽出 し 、 与信 リ ク エ ス ト と と も に送信 し ます。 12 検証に失敗 し た場合、 ユーザに対 し こ のカー ド での取引がで き ない旨を表示 し ま す。

与信 リ ク エ ス ト と の組み合わせ

本人認証サービ ス の結果は ク レ ジ ッ ト カー ド の与信 リ ク エ ス ト に フ ィ ール ド と し て追 加 し 、 送信す る 必要があ り ま す。 サ イ バー ソ ー ス の ク レ ジ ッ ト カー ド 決済サービ ス を 利用 し てい る 場合な ら 、 与信 リ ク エ ス ト を本人認証サービ ス リ ク エ ス ト と 同時に呼び 出す こ と がで き ます。

登録確認 と 同時に与信を リ ク エ ス ト

サ イ バー ソ ー ス は最初に登録確認を行い ます。 その結果ユーザが本人認証プ ロ グ ラ ム に登録 さ れて い な い ま た は発行会社が本人認証プ ロ グ ラ ム に参加 し て い な い場合に は、 与信の処理に進みま す。 本人認証サービ ス の結果な ど の必要な情報は自動で与信 リ ク エ ス ト に渡 さ れ ます。 Note 本人認証登録な し の場合について、 多 く の場合でチ ャ ージバ ッ ク 保護を受け る こ と がで き ます。 （チ ャ ージバ ッ ク 保護についてはApppendix A チ ャ ージバ ッ ク保護の 概要を参照 し て く だ さ い。） 検証 ユーザ マーチ ャ ン ト サーバ サ イ バー ソ ース 検証 10 12 9 8 PARes 11

本人認証サービ スの概要 ユーザが本人認証プ ロ グ ラ ム に登録 さ れてい る 場合には、 本人認証の次の段階、 検証 を行 う 必要があ り ます。 （与信処理は実行 さ れ ません）

検証 と 同時に与信を リ ク エ ス ト

サ イ バー ソ ー ス は最初に検証を処理 し ます。 検証に成功す る と 、 ク レ ジ ッ ト カー ド の 与信処理に進みま す。 検証に失敗 し た場合には、 与信処理は実行 さ れ ま せん。 本人認 証サービ ス の結果な ど の必要な情報は自動で与信 リ ク エ ス ト に渡 さ れ ます。

与信を別途 リ ク エ ス ト

与信に必要な本人認証サービ ス の結果の値を保存 し てお き 、 別途 ク レ ジ ッ ト カー ド 決 済を リ ク エ ス ト す る こ と も 可能です。 こ の場合には、 必要な情報を必ず与信 リ ク エ ス ト に設定 し て く だ さ い。 正 し く 設定が行われていない と 、 チ ャ ージバ ッ ク 保護を受け る こ と がで き ません。与信に加え る 必要のあ る 情報については表 3、表 4 「ccAuthService に追加す る 必要のあ る デー タ 」 （シ ン プルAPI） ま たは表 11、 表 12 「ics_auth に追加す る 必要のあ る デー タ 」 （SCMP) を参照 し て く だ さ い。 図 3 本人認証サービ ス と 与信の組み合わせ処理フ ロー

本人認証サービ スのオプ シ ョ ン

本人認証を確実に行 う ために以下の二つのチ ェ ッ ク を行 う こ と を推奨いた し ます。 • リ ク エ ス ト と 返 り 値に含まれ る XID を比較する ：

XID と は、 個々の PAReq （Payment Authentication Request 本人認証 リ ク エ ス ト ） に 対 し 生成 さ れ る 一意の （同 じ ID が存在せず重複 し ない） ID です。 カー ド 発行会 社 よ り 返 る PARes （Payment Authentication Response 本人認証レ ス ポン ス） は、 対

登録確認 検証 与信 与信 登録あり 登録なし 認証＋与信 登録確認＋与信 失敗 処理終了 (販売せず) 処理終了 (販売せず) 処理終了 (販売せず) 処理終了 (取引成立) 処理終了 (取引成立) OK OK 成功 失敗 失敗

応す る PAReq に含まれていた XID を含みます。 PAReq と PARes の両方の XID を 比較す る こ と で本人認証が正 し く 行われたか ど う か を確認す る こ と がで き ます。 • 本人認証に使用 さ れた カー ド 番号 と 、 与信に使用 さ れた カー ド 番号を比較す る ： PARes がカー ド 発行会社で一度生成 さ れ る と 、 その中に含まれ る ユーザのカー ド 番号については変更が不可能です。 こ れを利用 し て、 本人認証を取得 し た カー ド 番号 と 実際に与信に使用 さ れた カー ド 番号が同一で あ る か ど う か を確認 し ま す。 検証 リ ク エ ス ト にカー ド 番号を送信す る と 、 サ イ バー ソ ース はPARes に含まれ る カー ド 番号 と の照会を行い、 一致 し ない場合にはエ ラ ーを返 し ます。

導入にあた っ て

本人認証サービ ス を導入す る にあ た っ て具体的に EC サ イ ト に加え るべき変更は、 次 の通 り です。 1 チ ェ ッ ク ア ウ ト の際、 ク レ ジ ッ ト カー ド での支払いに対 し て、 本人認証サービ ス の対象 と な る カー ド か ど う か を判断 し ます。 ク レ ジ ッ ト カー ド 番号の最初の 1 桁 が、4 な ら Visa、 5 は MasterCard、 35 が JCB です。 2 ユーザのカー ド がVisa、 MasterCard、 JCB のいずれかであ っ た場合には、 与信を リ ク エ ス ト す る 前 に 登 録 確 認 の リ ク エ ス ト を サ イ バ ー ソ ー ス に 送 信 し ま す。 （American Express や Diners 等の本人認証サービ ス に対応 し ていないカー ド の場合 には登録確認 リ ク エ ス ト を送信 し ないで く だ さ い）

3 登録確認の リ プ ラ イ を確認 し 、 ユーザが本人認証プ ロ グ ラ ム に登録 さ れていた場 合は PAReq と と も にユーザの カー ド 発行会社の ACS に リ ダ イ レ ク ト し ま す。 （hidden 属性のみで構成 さ れ る form ページ を作成 し 、 ACS サーバの URL に POST で送信 し ます。）

• 必要な フ ィ ール ド と 値 　

• こ のform ページは JavaScript を使っ て、読み込み時に自動的に POST さ れ る よ う に し ます。 • ACS サーバの URL は登録確認 リ ク エ ス ト の リ プ ラ イ と し て戻 り ます。 ユーザ は こ のURL に リ ダ イ レ ク ト さ れ、本人認証のためのパス ワー ド を入力 し ます。 • ユーザのブ ラ ウ ザ設定に よ っ て はブ ロ ッ ク さ れ て し ま う 可能性が あ る た め、 ポ ッ プア ッ プ ウ ィ ン ド ウ ではな く 、ア ク テ ィ ブなブ ラ ウ ザ画面 と し て遷移 さ せ る よ う 推奨 し ます。 4 本人認証画面でユーザがパ ス ワー ド を入力す る と 、ACS サーバは認証結果（PARes） をTermURL に POST し ます。 こ の情報を検証 リ ク エ ス ト に渡 し ます。 PARes には次の フ ィ ール ド があ り ます。 PaReq 登録確認 リ ク エス ト の リ プ ラ イ と し て返るPAReq。 こ こ でのフ ィ ール ド 名はP の次の a が小文字 (PaReq) である こ と にご注意下 さ い。 TermUrl カ ー ド 発行会社か らの リ プ ラ イ （PARes） を受け取っ て処理する自サイ

ト のURL （通常は CGI、 servlet など を指定 し ます）

MD 注文番号な どのマーチ ャ ン ト デー タ （Merchant data）。 この値はカー ド 会社側で使用 さ れる こ と はな く 、 一切変更 さ れずに” TermURL” に引 き渡 さ れます。 フ ィ ール ド 自体は必須なので、 特に設定する必要のない 場合は値を ブ ラ ン ク と し て下 さ い。 PaRes デジ タ ル署名 さ れたPARes。 本人認証の結果 （成功／失敗） と ト ラ ンザク シ ョ ンの詳細情報が含まれます。 フ ィ ール ド 名はP の次の a が小文字 (PaReq) である こ と にご注意下 さ い。 MD 送信 し たMD がそのままセ ッ ト さ れます

導入にあた っ て Note 本人認証の結果が成功なのか失敗なのか、 ま たはAttempt なのかは、 デジ タ ル署名 さ れたPARes では判断で き ません。 検証の リ プ ラ イ の情報で確認する こ と がで き ます。 5 サ イ バー ソ ース に検証 リ ク エ ス ト を送信 し ます。 6 本人認証の結果や関連の情報を検証 リ ク エ ス ト の リ プ ラ イ と し て受信 し ます。 • ECI (Electronic Commerce Indicator) および XID

• Visa および JCB の場合 ： CAVV (cardholder authentication verification value) MasterCard の場合 ： AVV (account authentication value)

7 本人認証の結果を う け て、 注文を受け付け る か ど う かの判断を し ます。 注文を受 け付け る 場合には、 与信処理に進み ます。 こ の際、 与信 リ ク エ ス ト に際 し ては前 述の6 にあ る情報が正 し く セ ッ ト さ れてい る こ と が必要です。

注文を受け付け る か ど う かの判断についてはチ ャ ージバ ッ ク 保護についてを参照 し て く だ さ い。

シ ン プル

API

本章ではSCMP APIか ら 本人認証サービ ス を利用する方法およ びテ ス ト の情報について 説明 し ます。 本章は次のセ ク シ ョ ン で構成 さ れてい ます。 • API の紹介 • リ ク エ ス ト の作成 と リ プ ラ イの解釈 • 本人認証サービ ス • API フ ィ ール ド

API の紹介

シ ン プル

API ク ラ イ ア ン ト

ICS サービ ス へのア ク セ ス に使用 さ れ る メ ッ セージの完全性 と プ ラ イ バシーを確保す る ため、サ イ バー ソ ース はすべての メ ッ セージについて WS-Security 標準に準拠 し たデ ジ タ ル署名の適用を強 く 推奨 し ます。 シ ン プルAPI ク ラ イ ア ン ト には、 以下が含まれてい ます。 • サ イ バー ソ ース と の通信お よび ICS サービ スへのア ク セ ス に使われ る ク ラ イ ア ン ト ラ イ ブ ラ リ • メ ッ セージのデジ タ ル署名に使われ る セキ ュ リ テ ィ ラ イ ブ ラ リ • SOAP ユーザーの場合は、 SOAP プ ロ キ シ ク ラ ス • メ ッ セージのデジ タ ル署名お よ び ク ラ イ ア ン ト ラ イ ブ ラ リ の使用のためのサ ン プ ル コ ー ド 利用可能な シ ン プルAPI ク ラ イ ア ン ト の最新一覧お よ び関連マニ ュ アルについては、サ ポー ト セ ン タ ーのダ ウ ン ロ ー ド ページ を参照 し て く だ さ い。

API のバージ ョ ン

サ イ バー ソ ース は、新 し い API フ ィ ール ド の追加お よ び機能性の拡充をはか る ために、 シ ン プルAPI を定期的に更新 し てい ます。API には更新ご と に新 し いバージ ョ ン番号が 付 き ます( 例 : 1.38）。最新バージ ョ ンの API を ご利用いただいてい る か判断いただ く た めには、 以下のURL を ご覧 く だ さ い。 https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/ ICS サービ ス のすべての機能を ご利用いただ く ためには、最新バージ ョ ン を使用する必 要があ り ます。シ ン プルAPI ク ラ イ ア ン ト の設定の場合には、使用する API のバージ ョ ン を指定 し ます( 指示手順につき ま し ては、 ご使用の ク ラ イ ア ン ト にあわせて開発者ガ イ ド を参照 し て く だ さ い)。

デー タ 型の定義

本章で用いてい る デー タ 型式の定義は以下の と お り です。 • 数値 - 数値全体。 {... -3、 -2、 -1、 0、 1、 2、 3...}

API の紹介

• 文字列 - 文字、 数値、 スペース、 特殊文字 (@ や # な ど ) を含む。

日本語入力について

ク レ ジ ッ ト カー ド 決済お よ び本人認証サービ ス はマルチバ イ ト 文字を サポー ト し てい ます。

シ ン プル API においては、 Java 以外の ク ラ イ ア ン ト は UTF-8 をサポー ト し てい ます。 文字列の入力が可能な フ ィ ール ド に日本語の値を設定す る こ と がで き ます。 文字 コ ー ド の設定については各 ク ラ イ ア ン ト の開発者ガ イ ド を ご参照 く だ さ い。

ICS サービ スへのア ク セス

サ イ バー ソ ース シ ンプル API では、 名前 / 値ペア ま たは XML のいずれかを使用 し て ICS サー ビ ス へア ク セ ス す る こ と が可能です。 使用 さ れて い る プ ラ ッ ト フ ォ ー ム に よ っ ては、SOAP のご使用 も 可能です。 SOAP イ ン タ ーフ ェ イ ス に関する詳細について は、 サ イ バー ソ ース カ ス タ マーサポー ト ま でお問い合わせ く だ さ い。 名前/ 値 ペアは、XML ス キーマに基づいてい ます。XML を ご利用にな る場合には、 こ のガ イ ド の名前/ 値ペアに関する説明を、 対応する XML 要素に読み替えて く だ さ い。 サ イ バー ソ ー ス ICS サービ ス を リ ク エ ス ト す る には、 次の と お り コ ー ド を記述す る 必 要があ り ます。 • 使用す る ICS サービ ス の情報を収集する • 注文情報を リ ク エ ス ト に組み込む • リ ク エ ス ト を サ イ バー ソ ース サーバに送信する • リ プ ラ イ 情報を処理す る リ ク エ ス ト お よ び リ プ ラ イ の例については、Apppendix D リ ク エ ス ト と リ プ ラ イのサン プルを参照 し て く だ さ い。

名前

/ 値ペア及び XML のフ ィ ール ド 名の相関関係について

名前/ 値ペア と XML で使用 さ れ る、 リ ク エ ス ト 及び リ プ ラ イ におけ る フ ィ ール ド 名の それぞれの関連性は次の通 り です。 • 名前/ 値ペアのフ ィ ール ド 名は、 それぞれ XML の要素名に対応 し てい ます。 • XML の要素の親子関係については、名前/値ペアの フ ィ ール ド 名においてア ン ダー ス コ ア(_) で区切っ て表 し てい ます。 例 フ ィ ール ド 名が文字列の場合 XML では <billTo> と い う 要素が、 い く つかの子要素を も っ ています。表 1 は、XML での要素名 と 、 名前/ 値ペアのフ ィ ール ド 名の関係を示 し た も のです。 表 1 ： XML スキーマ と フ ィ ール ド 名の関係の例 XML スキーマ 対応する名前/ 値ペアの フ ィ ール ド 名 <billTo> <firstName> <lastName> <city> </billTo> billTo_firstName billTo_lastName billTo_city

例 数字を含むフ ィ ール ド の場合 XML ス キーマには、 数字 と 組み合わせる こ と で リ ク エ ス ト に複数含め る こ と ので き る 要素があ り ます。 例えば、 商品情報を指定す る 要素 <item> は、 それぞれ ０ か ら 始ま る 通 し 番号をつけて複数の商品情報を指定 し ます。XML ス キーマでは、 id 属性を使用 す る こ と で通 し 番号をつけ ます。 例えば ： <item id="0"> 一方、 名前/ 値ペアでは、 フ ィ ール ド 名を item_0 と 表 し ます。 こ の場合は、 ア ン ダー ス コ アは要素の親子関係の区切 り ではあ り ません。 商品情報を指定す るitem フ ィ ール ド の名前は、item_#_< 要素名 > と な っ てい ます。 表 2 は、 <item> 要素の名前 / 値ペアのフ ィ ール ド 名 と の関係を示 し てい ます。 Note SOAP を利用 さ れ る場合には、 XML ス キーマでの複合型は同 じ 名前の ク ラ ス に 変換 さ れ ます。 例えば、 複合型<billTo> は SOAP ク ラ イ ア ン ト では billTo ク ラ ス と な

り ます。

リ ク エ ス ト の作成 と リ プ ラ イの解釈

リ ク エ ス ト を構築する

ICS サービ ス の リ ク エ ス ト は、 「マーチ ャ ン ト やユーザに関する一般的な情報」 と 、 「 リ ク エ ス ト す る サービ ス に特有の情報」 か ら な り ます。 商品名、 単価、 数量な ど EC サ イ ト 等での商品に関する情報は、 item_# と い う フ ィ ー ル ド で指定 し ます。item_0、 item_1... と 通 し 番号にな っ てい ます。 item_# の フ ィ ール ド 値にキ ャ レ ッ ト (^) ま たは コ ロ ン (:) を使用する こ と はで き ません。 すべての リ ク エ ス ト フ ィ ール ド では、埋め込みスペースや、他の文字記号は使用で き ますが、改行やキ ャ リ ッ ジ リ タ ーン を使用す る こ と はで き ません。 値の一番初め ま たは最後にあ る ス ペー ス は処理の際に取 り 除かれ ます。 特に注意のない限 り 、 フ ィ ール ド 名は大文字小文字を区別 し 、値には@, #, % な どの記 号が使用で き ます。 ス キーマの構造は、 リ ク エ ス ト メ ッ セージ と リ プ ラ イ メ ッ セージ と に分かれ ます。 リ ク エ ス ト メ ッ セージには取引や商品、 サービ ス に固有の情報に関す る 要素が含ま れ ま す。例えば、ク レ ジ ッ ト カー ド 決済での与信 リ ク エ ス ト に固有の情報は<ccAuthService> と い う 要素内にあ り ます。 表 2 ： 番号のついた XML スキーマ と フ ィ ール ド 名の関係の例 XML スキーマ 対応する名前/ 値ペアの フ ィ ール ド 名 <item id="0"> <unitPrice> <quantity> </item> item_0_unitPrice item_0_quantity <item id="1"> <unitPrice> <quantity> </item> item_1_unitPrice item_1_quantity

リ ク エス ト の作成 と リ プ ラ イの解釈

『サービ ス を実行 し たい』 と い う こ と を リ ク エ ス ト で示すには、 サービ ス要素のrun 属 性を 「true」 に設定 し ます。 た と えば、 ク レ ジ ッ ト カー ド 与信を リ ク エ ス ト す る には、 <ccAuthService> 要素の run 属性を 「true」 に設定 し ます。 サービ ス の リ ク エ ス ト に関す

る 詳 し い情報は、サービ スの リ ク エ ス トを参照 し て く だ さ い。 本番環境の ト ラ ン ザ ク シ ョ ン の場合は、XML ス キーマが あ る https://ics2ws.ic3.com/ commerce/1.x/transactionProcessor に リ ク エ ス ト を送信 し ます。 テ ス ト ト ラ ンザ ク シ ョ ン の場合は、https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor に リ ク エ ス ト を送 信 し ます。

リ プ ラ イ を解析する

サ イ バー ソ ース サーバに よ っ て リ ク エ ス ト 処理後、 リ ク エ ス ト し たサービ ス に関する 情報を含んだ リ プ ラ イ メ ッ セージが送信 さ れ ます。 リ プ ラ イ メ ッ セージには、 リ ク エ ス ト 全体に対す る 一般的な情報 と 、 リ ク エ ス ト し たサービ ス の結果に関 し ての情報が 含 ま れ ま す。 た と え ば、 ク レ ジ ッ ト カ ー ド 与 信 に 関 連 す る リ プ ラ イ 情 報 は、 <ccAuthReply> 要素内にあ り ます。 リ プ ラ イ の解釈方法に関する詳細については、リ プ ラ イの解釈を参照 し て く だ さ い。 サ イ バー ソ ース か ら の XML リ プ ラ イ には、 必ずネーム スペース と し て最初に c: が含 まれます。 ネーム スペース をサポー ト す るXML パーサーを使用する必要があ り ます。 リ プ ラ イ 情報を利用す る ためには、 シ ス テ ムや リ プ ラ イ デー タ を必要 と す る 他のシ ス テ ム に対 し て こ う い っ たデー タ を組み入れてい く 必要があ り ま す。 た と えば、 デー タ ベー ス に リ プ ラ イ 情報を保存 し て、 その情報を他のバ ッ ク オ フ ィ ス アプ リ ケーシ ョ ン に送信 し ます。 リ プ ラ イ 情報 ま た はエ ラ ー メ ッ セージ を ユーザに直接表示す る こ と はせずに、 サ イ バー ソ ー ス か ら 受信 し た リ プ ラ イ コ ー ド お よ び リ プ ラ イ フ ラ グ を 処理す る た めのエ ラ ーハン ド ラ を記述す る こ と でユーザには状況に応 じ て適切な メ ッ セージ を伝え る よ う に し て く だ さ い。 重要 リ プ ラ イ フ ィ ール ド 及び理由 コ ー ド はサ イ バー ソ ー ス において新たに追加 さ れ る こ と があ り ま す。 そのため、 リ プ ラ イ デー タ を解析 さ れ る 際には、 そのデー タ の順 番ではな く 、 フ ィ ール ド 名に基づいて解析 し ていただ く よ う にお願いいた し ます。 エ ラ ーハン ド ラ は、 認識で き ない理由 コ ー ド が返っ て き た場合に も 、decision フ ィ ール ド を元に処理を行え る よ う に し て く だ さ い。

判定

リ プ ラ イ では、 リ ク エ ス ト の結果全体が集約 さ れた判定フ ィ ール ド decision を受信 し ます。 decision と は リ ク エ ス ト の結果を表す 1 単語です。 まず こ の フ ィ ール ド を確認 し 、 その後のア ク シ ョ ン を判断 し ます。decision の値 は、 次のいずれかにな り ます。 • ACCEPT: リ ク エ ス ト が正常に完了 し た場合 • ERROR: シ ス テ ムエ ラ ーがあ る場合 • REJECT: リ ク エ ス ト 内のサービ ス の 1 つま たは複数が拒否 さ れた場合 シ ス テ ム エ ラ ーは、 リ ク エ ス ト の内容自体 と は関係な く 、 シ ス テ ム の問題が原因 と な り 発生す る も のです。 リ ク エ ス ト は、 サ イ バー ソ ー ス、 プ ロ セ ッ サー、 ま たはカー ド 会社に よ っ て拒否 さ れ る こ と があ り ます。 た と えば、 サ イ バー ソ ース は、 必須フ ィ ール ド が抜けていた り 無 効なデー タ が含ま れ る 場合には リ ク エ ス ト の受付を拒否 し ます。 ま た、 カー ド 会社は、 カー ド 限度額に達 し た場合やカー ド の利用が停止 さ れてい る 場合等に リ ク エ ス ト を拒 否 し ます。 リ ク エ ス ト 拒否の理由を特定す る には、reasonCode （理由コー ド ） フ ィ ー ル ド を使用 し て く だ さ い。 成功お よ び拒否 さ れたすべての リ ク エ ス ト について、 料金が課金 さ れ ます。 エ ラ ー と な っ た リ ク エ ス ト については、 料金は課金 さ れ ません。

理由 コ ー ド

decision （判定値） の理由に関す る 詳細情報に関 し ては、 ２ 種類の reasonCode （理由 コ ー ド ） フ ィ ール ド が返 さ れ ます。 • reasonCode こ の フ ィ ール ド は、 リ ク エ ス ト 全体の結果を示 し ます。 • < サービ ス >_reasonCode こ の フ ィ ール ド は、 リ ク エ ス ト し た個々のサービ ス の結果を示 し ます。 た と えば、 本人認証の登録確認を リ ク エ ス ト す る と 、 リ プ ラ イ では payerAuthEnrollReply_ reasonCode （本人認証に関する リ プ ラ イ _ 理由コー ド ） が返 さ れます。 こ れ ら の フ ィ ール ド は、 シ ス テ ム をデバ ッ グす る 際に便利です。

decision フ ィ ール ド を確認 し た後、reasonCode フ ィ ール ド に示 さ れ る reasonCode を用 いて各サービ ス の成功ま たは失敗についての判断の理由を特定 し 、 さ ら な る 処理を行

う か ど う か を決定 し ます。

• decision が ERROR の場合、 reasonCode は、 発生 し たエ ラ ーの タ イ プを示 し ます。 • decision が REJECT の場合、 reasonCode は、 拒否の理由 と 、 注文を成功 さ せる た

めの再処理が可能で あ る か ど う か を示 し ま す。 本人認証サービ ス の理由 コ ー ド に 関す る 説明については、理由 コ ー ドを参照 し て く だ さ い。

欠けている または無効な フ ィ ール ド

リ ク エ ス ト に必須フ ィ ール ド が欠け てい る 場合、 ま たは リ ク エ ス ト に無効なデー タ が 含 ま れ て い る 場合は、 特定の理由 コ ー ド が返信 さ れ ま す。 ま た理由 コ ー ド に加え て missingField_0...N お よ び invalidField_0...N と い う リ プ ラ イ フ ィ ール ド を受信 し ます。 こ れは、 修正が必要な フ ィ ール ド について示 し た一覧です。 た と えば、 ひ と つの リ ク エ ス ト に 対 し て 3 つ の 必須 フ ィ ー ル ド が 欠 け て い る 場合 に は、 missingField_0、 missingField_1、 missingField_2 の 3 つの リ プ ラ イ フ ィ ール ド が返信 さ れます。 こ れ ら の フ ィ ール ド を修正 し た後に、 リ ク エ ス ト を再送信す る 必要があ り ます。

Note XML の場合、<missingField> および <invalidField> 要素は番号付けは さ れません。 こ れに代わ り 、 リ プ ラ イ で<missingField> ま たは <invalidField> 要素が複数返信 さ れま す。 SOAP を ご使用の場合については、 一連の 「欠けてい る フ ィ ール ド 」 お よ び該当 す る 「無効な フ ィ ール ド 」 が返信 さ れ ます。

注文の追跡

API は、 注文を追跡する ための ID の役目をする さ ま ざ ま な フ ィ ール ド を提供 し ます。

注文番号

merchantReferenceCode （マーチ ャ ン ト リ フ ァ レ ン ス コ ー ド ： 注文番号） と は、 マー チ ャ ン ト が リ ク エ ス ト を送信す る 際に設定す る こ と ので き る 注文番号です。 注文番号 を記録 し ておいていただ く こ と でサ イ バー ソ ース のシ ス テ ム に対す る １ 件の注文につ いて複数に ま たが る サービ ス リ ク エ ス ト に関 し merchantReferenceCode を用いて追跡 す る こ と がで き ます。 Note サ イ バー ソ ース は注文毎に一意の注文番号を使 う こ と を推奨いた し ます。 例 1 つの注文で複数の処理を実行する場合 • 注文受付時に、 ク レ ジ ッ ト カー ド 与信取得のための リ ク エ ス ト を送信 し ます。 • 翌日、 商品を出荷 し 、 売上処理を行 う ための リ ク エ ス ト を送信 し ます。

本人認証サービ ス • 1 週間後、 ユーザが商品を返品。 こ の際に返金処理を リ ク エ ス ト し ます。 こ の 1 つの注文に付随 し たそれぞれの異な る サービ ス を実行する ためには 3 つの個別 の リ ク エ ス ト を 送 信 す る 必 要 が あ り ま す。 各 リ ク エ ス ト の 実 行 時 に 同 じ merchantReferenceCode を利用 し て リ ク エ ス ト を送信す る と 、 その後に管理画面 「ビ ジネ ス セ ン タ ー」 な ど を利用 し て効率的に注文状況を追跡す る こ と が可能です。

リ ク エ ス ト

ID

requestID （ リ ク エ ス ト ID） と は、 サ イ バー ソ ース のサーバに よ っ て リ ク エ ス ト が処 理 さ れた後、 送信 さ れ る リ プ ラ イ の中で、 サ イ バー ソ ース に よ っ て リ ク エ ス ト に割 り 当て ら れ る 一意のID です。 上記の例では、 各 リ ク エ ス ト に対する それぞれの リ プ ラ イ で異な るrequestID を受信する こ と にな り ます。 あ る ひ と つの リ ク エ ス ト に対 し 、 それに追加す る 形式で処理の リ ク エ ス ト を行 う 、 追 加型 （フ ォ ロ ーオ ン） 決済の場合に requestID を使用 し ます。 例えば、 ひ と つの注文 について、 ク レ ジ ッ ト カー ド の売上処理の リ ク エ ス ト を送信す る 際に、 与信処理 ト ラ ンザ ク シ ョ ンの際の requestID を指定 し ます。 サ イ バー ソ ース はその値を使用 し て売 上情報を特定す る ため、 売上 リ ク エ ス ト でマーチ ャ ン ト が指定すべ き 情報量は削減 さ れ ます。 ま た、requestID を特定の リ ク エ ス ト について カ ス タ マーサポー ト に状況確認 をす る 際な ど に用いていただ く と 便利です。

リ ク エ ス ト ト ー ク ン

requestToken （ リ ク エ ス ト ト ー ク ン） と は、 リ ク エ ス ト に一意の、 リ ク エ ス ト 情報を エ ン コ ー ド （暗号化） し た文字列です。 カー ド 番号な どの機密情報が入る こ と はあ り ま せん。 基本的に256 桁以下の文字列 （記号を含む英数字） で構成 さ れてい ます。 API を介 し て各種の追加型処理を行 う 際には、 こ の リ ク エ ス ト ト ー ク ンが必要にな り ます。

本人認証サービ ス

こ のセ ク シ ョ ン では、 本人認証サービ ス の詳細 と 、 各フ ィ ール ド （ リ ク エ ス ト 、 リ プ ラ イ ） お よ び理由 コ ー ド について説明 し ます。

利用可能な ア プ リ ケーシ ョ ン

サ イ バー ソ ース に対 し 、 リ ク エ ス ト が可能な アプ リ ケーシ ョ ンは、 以下の と お り です。 • payerAuthEnrollService （登録確認） : ユーザ （ ク レ ジ ッ ト カー ド 会員） の本人認 証プ ロ グ ラ ムへの登録の有無を確認 し ます。 • payerAuthValidateService （検証） : カー ド 発行会社の ACS サーバか ら 受け取っ た PARes を検証 し 、 与信処理に必要な値を返 し ます。 本章の説明ではアプ リ ケーシ ョ ン名がそれぞれEnroll, Validate に省略 さ れてい ます。

本人認証サービ スで使われる識別子

サ イ バー ソ ース の本人認証サービ ス では、 以下の識別子が使われ ます

CAVV 　

Visa 認証サービ スおよ び JCB の提供する本人認証プ ロ グ ラ ム J/Secure にいて カー ド 発行会社が発行す る 一意の識別子です。 こ の識別子はユーザ （カー ド 会員） が 認証に成功す る と 発行 さ れ、PARes と し て受領 し ます。 展開 さ れた値は Validate の リ プ ラ イ フ ィ ール ド payerAuthValidateReply_cavv で返 り ます。 こ の値を与信 リ ク エ ス ト で送信す る 必要があ り ます。

AAV 　

MasterCard SecureCode プ ロ グ ラ ムでカー ド 発行会社が発行する一意の識別子で す。 ユーザが認証に成功す る と 発行 さ れ、 PARes と し て受領 し ます。 展開 さ れた値は

Validate の リ プ ラ イ フ ィ ール ド payerAuthValidateReply_ucafAuthenticationData で返 り ます。 こ の値は与信 リ ク エ ス ト で送信す る 必要があ り ます。

XID 　

サ イ バー ソ ース が発行す る 一意の識別子です。PAReq の XID は リ プ ラ イ フ ィ ー ル ド payerAuthEnrollReply_xid、 PARes の XID は payerAuthValidateReply_xid で返 り ます。PAReq と PARes で同 じ XID が含まれてい る かど う か確認する こ と で、 本人認証 が正 し く 行われたか ど う か を確認で き ます。

Note 上記の CAVV, XID, AAV の値は Base64 でエン コー ド さ れた値です。 こ の値は与 信 リ ク エ ス ト (ccAuthService) で送信 さ れ る と 、 適切な フ ォーマ ッ ト に変換 さ れて カー ド 会社に送信 さ れ ます。 与信 リ ク エ ス ト (ccAuthService) に加え るべき情報については サービ スの リ ク エ ス トで説明 し てい ます。

登録確認 （

Enroll)

Note 実際にはユーザ （カー ド 会員） が本人認証プ ロ グ ラ ム に登録 し ていない場合で も 、 多 く の ト ラ ン ザ ク シ ョ ン について 「登録あ り 」 の情報が返 さ れ ます。 こ れはカー ド 発行会社の Attempt 機能への対応の有無に依存 し ま す、 Attempt 機能につい て は Apppendix A チ ャ ージバ ッ ク 保護の概要を参照 し て く だ さ い。 重要 こ のサービ ス は、それぞれのサービ ス に対応 し てい る ク レ ジ ッ ト カー ド 種類にの み使用 し て く だ さ い。 サブ ス ク リ プシ ョ ン （継続型決済） サービ ス を利用 し た ト ラ ン ザ ク シ ョ ン で は、 チ ャ ー ジ バ ッ ク 保 護 を 受 け る こ と が で き な い た め、 payerAuthEnrollService を使用 し ないで く だ さ い。

サービ スの リ ク エ ス ト

登録確認 （Enroll） サービ ス を利用する には、 payerAuthEnrollService_run を true と 設 定 し ます。Enroll サービ ス は、 ユーザが本人認証サービ ス に登録 さ れてい る か ど う かを 確認 し ま す。 サー ビ ス の リ ク エ ス ト 時に使用す る フ ィ ール ド の一覧につい て は API フ ィ ール ドを、 リ ク エ ス ト お よ び リ プ ラ イ の例については Apppendix D リ ク エ ス ト と リ プ ラ イのサン プルを参照 し て く だ さ い。 Visa、 MasterCard、 JCB 以外の種類の ク レ ジ ッ ト カー ド につ き ま し ては現在本人認証 サービ ス に対応 し てい ません。payerAuthEnrollService を呼び出す前に ク レ ジ ッ ト カー ド 番号の最初の 1 桁を使っ てカー ド の種類を確認 し て く だ さ い。 ク レ ジ ッ ト カー ド 番 号の最初の1 桁は、Visa では 4、MasterCard では 5、JCB では 35 です。American Express、 Diners カー ド で payerAuthEnrollService を リ ク エ ス ト し ないで く だ さ い。

リ プ ラ イの解釈

理由 コ ー ド ：

475

ユーザが本人認証プ ロ グ ラ ムに登録 さ れてい る 場合には、 理由 コ ー ド 475 が返 さ れま す。 decision=REJECT reasonCode=475 payerAuthEnrollReply_reasonCode=475

本人認証サービ ス こ の際、 リ プ ラ イ フ ィ ール ド payerAuthEnrollReply_acsURL には、 カー ド 発行会社の 認証ダ イ ア ロ グのURL が含まれてい ます。 こ の URL にユーザを リ ダ イ レ ク ト し て く だ さ い。

理由 コ ー ド ：

100

次の場合は、 理由 コ ー ド 100 が返 さ れます。 リ ク エ ス ト 内の他のサービ スは正常に処 理 さ れ ます。 • ユーザが本人認証サービ ス に登録 さ れていない • イ シ ュ ア （カー ド 発行会社） が本人認証サービ ス に対応 し ていない ccAuthService お よび payerAuthEnrollService を同一の リ ク エ ス ト で呼び出 し た場合に は、 サ イ バー ソ ー ス は自動的に本人認証の結果を ク レ ジ ッ ト カー ド の与信 リ ク エ ス ト に渡 し 、 処理を実行 し ます。 ccAuthService と payerAuthEnrollService を別々の リ ク エ ス ト で送信する際には、登録 な し の場合にチ ャ ージバ ッ ク 保護を受けるを参照 し て く だ さ い。 リ プ ラ イ の例については、Apppendix D リ ク エ ス ト と リ プ ラ イのサン プルを参照 し て く だ さ い。 リ プ ラ イ は、 ど の種類のカー ド について も ほぼ同様です。

登録な し の場合にチ ャ ージバ ッ ク 保護を受ける

ユーザが本人認証プ ロ グ ラ ム に登録がない、 ま たは イ シ ュ ア （カー ド 発行会社） が本 人認証プ ロ グ ラ ム に参加 し ていない際にチ ャ ージバ ッ ク 保護を受け ら れ る 契約であ る 場合で、ccAuthService と payerAuthEnrollService を別々の リ ク エ ス ト で送信する際に は、payerAuthEnrollService の結果を受けて、 ccAuthService に必要な フ ィ ール ド を追 加 し た上で リ ク エ ス ト し ます。ccAuthService に追加すべき フ ィ ール ド は次の通 り です。 リ ク エ ス ト の例については Apppendix D リ ク エ ス ト と リ プ ラ イのサン プルを参照 し て く だ さ い。

検証

(Validate)

本人認証の結果を検証す る には、payerAuthValidateService_run を true と 設定 し ます。 サービ ス の リ ク エ ス ト 時に使用す る フ ィ ール ド については API フ ィ ール ドを参照 し 、 リ ク エ ス ト お よ び リ プ ラ イ の例については Apppendix D リ ク エ ス ト と リ プ ラ イのサン プルを参照 し て く だ さ い。 decision=Accept reasonCode=100 payerAuthEnrollReply_reasonCode=100 表 3 ： ccAuthService に追加する必要のあるデー タ 識別子 ccAuthService リ ク エ ス ト フ ィ ール ド 名 設定する値 E-commerce indicator ccAuthService_

commerceIndicator • vbv_attempted（ Visa 認証_{サービ ス）}

• spa (MasterCard SecureCode) • js_attempted (J/Secure) ECI raw ccAuthService_eciRaw 06

Collection indicator (MasterCard SecureCode のみ )

ucaf_

サービ スの リ ク エ ス ト

チ ャ ージバ ッ ク 保護を受け る ためには、与信ccAuthService に検証結果を添付する必要 があ り ます。ccAuthService は payerAuthValidateService と 同一の リ ク エ ス ト ま たは個 別の リ ク エ ス ト で利用で き ます。 重要 本人認証の結果の解釈 と その結果受け る こ と ので き る チ ャ ージバ ッ ク 保護につ いては、 カー ド 会社 と の加盟店契約ご と に個別に異な り ます。 加盟店契約の条件につ いて、 必ず確認をお願いいた し ます。

同一の リ ク エ ス ト 　

payerAuthValidateService および ccAuthService を同時に含めた 場合、 認証に成功す る と ICS は自動的にユーザの ク レ ジ ッ ト カー ド の与信を取得 し ま す。 こ の場合、 必要 と さ れ る フ ィ ール ド の値は自動的に与信 リ ク エ ス ト に渡 さ れ ます。

Note リ ク エ ス ト フ ィ ール ド businessRules_ignoreValidateResult が true に設定 さ れて お り 、ccAuthService および payerAuthValidateService を同時に呼び出す場合、 検証に 失敗 し た場合で も サ イ バー ソ ー ス はユーザの ク レ ジ ッ ト カー ド の与信処理 を 行い ま す。Visa、 MasterCard、 JCB すべてのカー ド において、 検証に失敗 し た場合に与信処理 に進む こ と は禁 じ ら れてい ます。そのため、こ の リ ク エ ス ト フ ィ ール ド はccAuthService 以外のICS サービ ス と の併用時にのみ使用する こ と をサ イ バー ソ ース は推奨 し ます。

個別の リ ク エ ス ト 　

最初にpayerAuthValidateService を、 次に ccAuthService を別々 の リ ク エ ス ト で送信す る 場合は、 表 4 にあ る フ ィ ール ド 名を使用 し て、 フ ィ ール ド の 値をccAuthService に設定する必要があ り ます。 こ れ ら の フ ィ ール ド と その内容に関す る 詳細については、 リ プ ラ イ フ ィ ール ドを参照 し て く だ さ い。

Note payerAuthValidateReply_cavv、 payerAuthValidateReply_xid お よ び payerAuthValidateReply_ucafAuthenticationData の値は、 base64 形式で返 さ れます。 ク レ ジ ッ ト カー ド 与信サービ ス を リ ク エ ス ト し 、 こ れ ら の値を送信 し た場合、 サ イ バー 表 4 ： ccAuthService に追加する必要のあるデー タ 識別子 payerAuthValidateService リ プ ラ イ フ ィ ール ド 名 ccAuthService リ ク エ ス ト フ ィ ール ド 名 XID payerAuthValidateReply_xid ccAuthService_xid

E-commerce indicator payerAuthValidateReply_

commerceIndicator ccAuthService_commerceIndicator

ECI raw PayerAuthValidateReply_eci_

raw ccAuthService_eciRaw CAVV (Visa 認証サービ ス、 J/Secure のみ ) payerAuthValidateReply_cavv ccAuthService_cavv AAV (MasterCard SecureCode のみ ) payerAuthValidateReply_ ucafAuthenticationData ucaf_authenticationData Collection indicator (MasterCard SecureCode のみ ) payerAuthValidateReply_ ucafCollectionIndicator ucaf_collectionIndicator

本人認証サービ ス ソ ー ス は自動的に フ ィ ール ド 名ではな く 値を、 各決済プ ロ セ ッ サで要求 さ れ る 形式に 変換 し ます。

リ プ ラ イの解釈

認証の検証 リ ク エ ス ト の結果を示すい く つかの リ プ ラ イ フ ィ ール ド が返 さ れ ます。 表 5 「Visa 認証サービ ス の場合の認証結果」 は、 Visa 認証サービ ス用のフ ィ ール ド と それ ら が取 り 得 る 値の関係を示 し てい ます。 表 6 「MasterCard SecureCode の場合の認 証結果」 はMasterCard SecureCode、 表 7 「J/Secure の場合の認証結果」 は J/Secure の場 合を それぞれ示 し てい ます。 本人認証の結果が正 し く 検証 さ れた場合は、 理由 コ ー ド 100 が返 さ れ、 リ ク エ ス ト 内 の他のすべてのアプ リ ケーシ ョ ンが正常に処理 さ れ ます。 本人認証の結果を検証で き なか っ た場合には、 理由 コ ー ド 476 が返 さ れ、 リ ク エ ス ト 内の他のアプ リ ケーシ ョ ンは実行 さ れ ません。 （ リ ク エ ス ト フ ィ ール ド businessRules_ ignoreValidateResult を true に設定する と 、 こ の拒否を回避で き ます。） Note 検証に失敗 し た場合は、 その同一の ク レ ジ ッ ト カー ド を利用 し ての注文を許可 し てはな ら ない こ と をVisa、 MasterCard お よび JCB は規定 し てい ます。 別の決済方法 を選択す る よ う にユーザに連絡す る 必要があ り ます。

Visa 認証サービ ス

表 5 は、 フ ィ ール ド と それ ら の取 り 得る値 と の関係を示 し てい ます。 . 表 5 ： Visa 認証サービ スの場合の認証結果 結果 と 解釈 payerAuthValidateReply_ authentication Result eci commerce Indicator reasonCode 成功 検証に成功 0 05 vbv 100 Attempt 1 06 vbv_attempted 100 失敗 （ユーザに責 任な し ） イ シ ュ ア （カ ー ド 発行会社） が認証 を実行で き ない等 6 07 internet 100 PARes が無効 -1 00 - 476 失敗 （ユー ザの責任） 認証に失敗、 また はカ ー ド 保有者が 認証を完了 し な か っ た 9 – – 476

MasterCard SecureCode

表 6 は、 フ ィ ール ド と それ ら の取 り 得る値の関係を示 し てい ます。 .

J/Secure

表 7 は、 フ ィ ール ド と それ ら の取 り 得る値の関係を示 し てい ます。 .

本人認証サービ スデー タ の保管

以下の フ ィ ール ド で返 さ れ る 値を保管 し てお く よ う に し て く だ さ い。 こ れ ら のデー タ については、 チ ャ ージバ ッ ク の発生時に、 本人認証を行っ た証拠 と し て カー ド 会社に 提示す る 必要があ り ます。 リ プ ラ イ の例については、Apppendix D リ ク エ ス ト と リ プ ラ 表 6 ： MasterCard SecureCode の場合の認証結果 結果 と 解釈 payerAuthValidateReply_ authentication Result ucaf Collection Indicator commerce Indicator reasonCode 成功 検証に成功 0 2 spa 100 Attempt 1 1 spa 100 失敗 （ユーザに 責任な し ） イ シ ュ ア （カ ー ド 発行会社） が認証 を実行で き ない等 6 1 internet 100 PARes が無効 -1 0 476 失敗 （ユーザの 責任） 認証に失敗、 また はカ ー ド 保有者が 認証を完了 し な か っ た 9 1 - 476 表 7 ： J/Secure の場合の認証結果 結果 と 解釈 payerAuthValidateReply_ authentication Result eci commerce Indicator reasonCode 成功 検証に成功 0 05 js 100 Attempt 1 06 js_attempted 100 失敗 （ユーザに 責任な し ） イ シ ュ ア （カ ー ド 発行会社） が認証 を実行で き ない等 6 07 internet 100 PARes が無効 -1 00 - 476 失敗 （ユーザの 責任） 認証に失敗、 また はカ ー ド 保有者が 認証を完了 し な か っ た 9 00 または – – 476

API フ ィ ール ド

イのサン プルを参照 し て く だ さ い。 リ プ ラ イ は、 ど の種類のカー ド について も ほぼ同 様の内容 と な り ます。

Note Enroll で登録な し の結果 と な っ た場合には、 XID は返 り ません。

payerAuthEnrollReply_proofXMLのみを保存す る よ う に し て く だ さ い。

サービ スのテ ス ト

サ イ バー ソ ー ス のテ ス ト サーバを利用 し て、 サービ ス のテ ス ト がで き ます。 テ ス ト に ついては本人認証サービ スのテ ス トを参照 し て く だ さ い。

API フ ィ ール ド

リ ク エ ス ト フ ィ ール ド

• payerAuthEnrollReply_ proofXML • payerAuthEnrollReply_ xid • payerAuthValidateReply_cavv • payerAuthValidateReply_eci • payerAuthValidateReply_ ucafAuthenticationData • payerAuthValidateReply_ ucafCollectionIndicator • payerAuthValidateReply_xid 表 8 ： シ ン プル API の リ ク エス ト フ ィ ール ド フ ィ ール ド 名 説明 サービ ス ( 必須 / オプ シ ョ ン) デー タ 型 および 最大長 billTo_customerID ユーザを特定する ためのID Enroll ( オプシ ョ ン ) Validate ( オプシ ョ ン ) 文字列 (50) businessRules_ ignoreValidateResult payerAuthValidateService を_{他のア プ リ ケーシ ョ ン と 同時に} 呼び出す場合に使用 し ます。 本 人認証に失敗 し た場合に他のア プ リ ケーシ ョ ン を実行するかど う か。 以下のいずれかの値を指 定 し ます。 • true: 本人認証の結果を 無視し て、 次のア プ リ ケーシ ョ ン を 実行し ま す • false: ( デフ ォ ルト ) 本 人認証が失敗し た場合、 処理はそこ でスト ッ プ し ま す Validate ( オプシ ョ ン ) 文字列(5) card_accountNumber ク レ ジ ッ ト カ ー ド 番号 Enroll( 必須 ) Validate ( オプシ ョ ン ) 正の整数 (20)

card_cardType ク レ ジ ッ ト カ ー ド の種類。 以下 のいずれかの値を指定 し ます。 • 001: Visa • 002: MasterCard • 007: JCB Enroll( 必須 ) Validate ( 必須 ) 文字列 (3) card_expirationMonth ク レ ジ ッ ト カ ー ド の期限月 (MM)。 card_accountNumber が指定 さ れてい る場合は必須 Enroll( 必須 ) Validate ** 文字列 (2) card_expirationYear ク レ ジ ッ ト カ ー ド の期限年 (YYYY)。 card_ accountNumber が指定 さ れて い る場合は必須 Enroll( 必須 ) Validate ** 文字列 (4) comments 注文に関する注記 Enroll ( オプシ ョ ン ) Validate ( オプシ ョ ン ) 文字列 （255） item_#_quantity 販売 さ れた商品の数量。 デ フ ォ ル ト は₁です。 Enroll ( オプシ ョ ン ) Validate ( オプシ ョ ン ) 数字 (10) item_#_taxAmount 商品にかかる税金の金額。 マ イ ナスの数値を設定する こ と はで き ません。 Enroll ( オプシ ョ ン ) Validate ( オプシ ョ ン ) 小数 (15) item_#_unitPrice 商品の単価。 マ イ ナスの数値を 設定する こ と はで き ません。 金 額の総計の計算時に、 小数点以 下の数値は通貨によ り 設定可能 な位で切 り 捨て られます。 Enroll( 必須 ) Validate ( 必須 ) 文字列 (15) merchantID サイバー ソ ース のマーチ ャ ン ト ID Enroll( 必須 ) Validate ( 必須 ) 文字列 (30) merchantReferenceCode マーチ ャ ン ト が生成 し た注文番 号 Enroll( 必須 )Validate ( 必須 ) 文字列 (50) payerAuthEnrollService_ httpAccept ユーザのブ ラ ウザか ら返 さ れる_{Accept: ヘ ッ ダーの値} Note 　ユ ー ザ の ブ ラ ウ ザが こ の値を返 し てい る場合は必ず指 定 し て く だ さ い。 Enroll ( オプシ ョ ン ) 文字列(255) payerAuthEnrollService_ httpUserAgent ユーザのブ ラ ウザか ら返 さ れる _{User-Agent: ヘ ッ ダーの値} Note 　ユ ー ザ の ブ ラ ウ ザが こ の値を返 し てい る場合は必ず指 定 し て く だ さ い。 Enroll ( オプシ ョ ン ) 文字列 (255) payerAuthEnrollService_

run Enroll を実行する場合には_{true を設定 し ます。} Enroll( 必須 ) 文字列(5) 表 8 ： シ ン プル API の リ ク エス ト フ ィ ール ド （続き） フ ィ ール ド 名 説明 サービ ス ( 必須 / オプ シ ョ ン) デー タ 型 および 最大長

API フ ィ ール ド ** Tips ** 税金額を設定する ク レ ジ ッ ト カー ド 決済では、 与信は税込みの合計金額を リ ク エ ス ト し ま す。 基本 的には item_#_unitPrice には税込みの金額 を 指定 し ま すが、 item_#_taxAmount フ ィ ール ド を利用 し て以下の よ う に指定す る こ と も 可能です。 こ の場合の合計金 額は3,150 円です。 item_0_unitPrice=1000 item_0_quantity=1 item_0_taxAmount=50 item_1_unitPrice=500 item_1_quantity=4 item_1_taxAmount=100

リ プ ラ イ フ ィ ール ド

payerAuthValidateService_ signedPARes ユーザのイ シ ュ アが返す本人認証の結果 メ ッ セージ(PARes) 。 Note 　こ の メ ッ セ ー ジ の 長 さ は様々で、 非常に長 く な る場合 も あ り ます。 すべての改行 コ ー ド （carriage return と line feeds） を削除 し て く だ さ い。

Validate

( 必須 ) 文字列 ( 制限 な し)

payerAuthValidateService_

run Validate を実行する場合には_{true を設定 し ます。} Validate( 必須 ) 文字列 (5)

purchaseTotals_currency ユーザが使用する通貨。 日本円

の場合には JPY を指定 し ます。 Enroll( 必須 )Validate ( 必須 ) 文字列 (5) purchaseTotals_ grandTotalAmount 注文の総合計金額。 この フ ィ ール ド またはitem_#_unitPrice の いずれかを リ ク エ ス ト に含める 必要があ り ます。 詳細について は、 ク レ ジ ッ ト カ ー ド 決済サー ビ ス導入ガ イ ド を参照 し て く だ さ い。 Enroll （オプ シ ョ ン） Validate （オプ シ ョ ン） 文字列 （15） 表 9 ： シ ン プル API の リ プ ラ イ フ ィ ール ド フ ィ ール ド 名 説明 サービ ス デー タ 型 と 最大長 decision リ ク エス ト 全体の結果を表 し ます。 こ のフ ィ ール ド には、 以下のいず れかの値が含まれます ： • ACCEPT • ERROR • REJECT Enroll Validate 文字列 (6) invalidField_0...N 無効なデー タ を含んだ リ ク エス ト フ ィ ール ド Enroll Validate 文字列 (100) merchantReferenceCode リ ク エス ト で指定 し た注文番号 Enroll Validate 文字列 (50) 表 8 ： シ ン プル API の リ ク エス ト フ ィ ール ド （続き） フ ィ ール ド 名 説明 サービ ス ( 必須 / オプ シ ョ ン) デー タ 型 および 最大長