웹표준결제연동가이드 INSTALL & SETUP GUIDE ( 주 )KG 이니시스
연동가이드작성자최재원검토자강석민 Page 2/55 e Copyright 2014 INICIS Co, Ltd. All rights reserved. 본문서와정보는 ( 주 ) 이니시스의재산입니다. 또한, 모든정보는 ( 주 ) 이니시스소유정보이며당사직원들에의한독점적사용만이허용됩니다. ( 주 ) 이니시스의사전동의없이본문서의어떤정보도열람, 복사, 유용, 배포또는타인과공유되어서는안됩니다. 본문서의정보는변경될수있으며변경시, 본문서는수정될것입니다. 본문서의내용에관한어떠한의견이라도귀하의프로젝트또는사업담당자에게전달하여주십시오. File: Title: Author: INIpay Standard 가맹점인터페이스규격서.doc 웹표준결제연동가이드 이니시스 Version: 1.3.1
연동가이드작성자최재원검토자강석민 Page 3/55 변경이력 작성일자 버젼 변경내역 작성자 2015-08-05 0.9.1 네이버제공편집 강석민 2015-08-18 0.9.2 설치가이드추가 강석민 2015-09-05 0.9.3 결제결과정보추가 강석민 2015-09-08 0.9.4 설치가이드오류정보수정 강석민 2015-09-14 0.9.5 결제요청페이지의 signkey정보추가 강석민 2015-09-22 0.9.6 29page 승인요청데이터정보추가, 21page 테스트용정보추가 강석민 2015-09-24 1.0.0 signkey 발급방법내용추가 강석민 2015-10-16 1.0.1 iframe, popup 크기추가, mobile 여부삭제, asp 샘플추가 강석민 2015-10-29 1.0.2 리턴값수정 강석민 2015-11-02 1.0.3 U-point 결제시리턴추가값조정 강석민 2015-11-11 1.0.4 결제수단관련테스트아이디로승인정보수정 오소영 2015-11-12 1.0.5 과세, 비과세기능추가 오소영 2015-11-13 1.0.6 PHP 5.3버전으로수정 오소영 2015-11-17 1.0.7 신에스크로구분자추가 오소영 2015-11-23 1.0.8 팝업허용여부체크추가 강석민 2015-12-04 1.0.9 은행사코드변경 강석민 2015-12-07 1.1.0 무통장 acceptmethod vbanknoreg 수정 강석민 2015-12-15 1.1.1 buyeremail 선택값으로수정 오소영 2015-12-17 1.1.2 필드명수정 ( 통신사 ) 오소영 2015-12-18 1.1.3 샘플라이브러리제공에대한내용수정 오소영 2015-12-21 1.1.4 tax필드명부가세로변경 오소영 2015-12-21 1.1.5 vbanknoreg 제거 ( 미사용권장 ) 강석민 2015-12-30 1.1.6 paymethod 리턴값설명강화 오소영 2016-01-05 1.1.7 요청카드코드, 승인카드코드분리 오소영 2016-01-08 1.1.8 mkey 필드값명시, payviewtype:popup삭제 오소영 2016-02-03 1.1.9 부분취소가능여부추가 오소영 2016-02-23 1.2.0 USD일경우 ISP 결제불가추가 오소영 2016-03-16 1.2.1 INIpay_Sample_v1.2.jar ->INIpay_Sample_v1.3.jar 변경 오소영 2016-04-21 1.2.2 A.6 은행 ( 증권사 ) 코드추가 강석민 2016-08-01 1.2.3 한미은행코드 (15) 씨티로변경 (43) 및추가 강석민 2016-08-30 1.2.4 신용카드빌링키발급추가 강석민 2016-09-02 1.2.5 소프트웨어요구사항 PHP 버전수정 최재원 2016-09-29 1.2.6 방화벽내용수정및에스크로결제추가 최재원 2016-11-03 1.2.7 가산 IDC 방화벽내용추가 강석민 2016-12-31 1.2.8 휴대폰빌링키발급추가승인결과데이터 ( 휴대폰결제 ) 통신사정보삭제 강석민
연동가이드작성자최재원검토자강석민 Page 4/55 2017-03-14 1.2.9 1. popup 미사용권장 2. asp.net dll파일구조수정 3. vbank 입금기한설정시예시문추가및초비제공문구 강석민 추가 4. 휴대폰빌링리턴값추가 2017-05-24 1.3.0 매뉴얼문서내 CI 변경작업 강석민 2017-07-12 1.3.1 1. 문화상품권응답필드추가 2. 스크립트 import 내용추가 최재원
연동가이드작성자최재원검토자강석민 Page 5/55 목차 1. 제품의개요및특징... 7 1.1 제품의개요... 7 1.2 제품의특징... 7 1.3 지불수단... 8 1.4 구조와결제처리흐름...13 1.4.1 결제요청... 13 2. 설치... 14 2.1 설치가능한운영체제...14 2.2 소프트웨어요구사항...14 2.3 하드웨어요구사항...14 2.4 방화벽설정...15 2.5 샘플소스...16 2.5.1 Java... 17 2.5.2 ASP.net... 18 2.5.3 ASP... 19 2.5.4 PHP... 20 2.6 파일 / 디렉터리권한...21 2.7 승인테스트...22 3. 결제연동... 23 3.1 결제요청페이지작성 (INIStdPayRequest)...23 3.1.1 결제요청데이터... 23 3.2 실시간신용카드빌링서비스작성 (INIStdPayBill)...31 3.2.1 실시간빌링서비스조건... 31 3.2.2 빌링키발급테스트... 31 3.3 에스크로결제...32 3.3.1 에스크로결제요청연동 (INIstdPayRequest).32
연동가이드작성자최재원검토자강석민 Page 6/55 3.3.2 에스크로구매확인연동 (INIescrow_confirm)..32 3.4 리턴페이지 ( 인증수신 / 승인API) 작성 (INIStdPayReturn)...34 3.4.1 인증결과수신... 34 3.4.2 승인API 요청... 34 3.4.3 승인API 결과 ( 결제완료 )... 36 3.5 Signature 생성...44 3.5.1 signature개요... 44 3.5.2 signature 첨부대상... 44 3.5.3 signature생성방법... 44 3.5.4 signature생성샘플 ( 결제요청 )... 45 3.6 결제취소페이지작성 (INIStdCancel)...46 3.7 승인취소요청페이지 (INIStdCancel.html)...46 3.8 승인취소및결과확인페이지...46 4. 별첨... 48 A.1. 결제수단코드 (gopaymethod)...48 A.2. 결제수단코드 (paymethod)...49 A.3. 카드사승인코드...49 A.4. 카드사코드 ( 결제창호출시제어코드 )...50 A.5. 카드발급사 ( 은행 ) 코드...50 A.6. 은행 ( 증권사 ) 코드...51 A.7. 카드이벤트적용코드...52 A.8. 인증결과코드...53 A.9. 승인결과코드...53
연동가이드작성자최재원검토자강석민 Page 7/55 1. 제품의개요및특징 1.1 제품의개요 INIpay Standard 전자지불시스템 은가맹점에서별도의모듈설치 (Non-ActiveX) 가없으며, 가상키보드의사용으로기존보안키보드등별도의보안프로그램설치없이이용이가능합니다. 또한 SHA256 Hash 를통한위변조방지와 HTTPS(SSL) 통신을이용하여보안이한층더강화된전자지불시스템입니다. 사용자의 PC (Windows, MAC ( 삼성, 롯데, 현대, NH, 신한 )) 환경에따라자동으로웹표준결제창을표시하며, 어떠한브라우저 (IE, Chrome, Firefox, Safari 등 ) 에서도추가적인설치없이원스톱사용이가능한전자지불솔루션입니다. INIpay Standard 는기존 INIpayTX 보다간편하고안전한, 신뢰성있는인터넷결제를도와주는인터넷지불솔루션입니다 1.2 제품의특징 INIpay Standard 전자지불시스템 은가맹점에서시스템의언어에구애받지않으며, 별도의모듈설치가필요없습니다. 또한 SHA256 hash, form POST 액션, HTTPS 통신만을이용한연동이가능합니다. Any Browser, Any OS 환경에서이니시스결제서비스를이용할수있습니다.( 현재지원 OS : windows, MacOS ( 삼성, 롯데, 현대, NH, 신한 ), 추후확대예정, 지원브라우저 : IE, Chrome, Firefox, Safari). INIpay Standard 는이니시스내부시스템에는웹표준기술만을사용하므로이니시스자체 ActiveX 프로그램 ( 플래쉬포함 ) 을설치하지않습니다. 하지만현재특정결제수단 ( 카드 ) 은인증기관 ( 카드사, 은행등 ) 의정책으로인해별도의 ActiveX 설치가필요할수있습니다. 그러나차후원천사에서웹표준을통한연동기술을도입시가맹점에서는새로운모듈연동의필요하지않으며, 일부결제요청전문의수정만으로웹표준서비스를제공받을수있습니다. Page 7
연동가이드작성자최재원검토자강석민 Page 8/55 1.3 지불수단 INIpay Standard 전자지불시스템 은결제의약 95% 를차지하는지불수단을지원합니다. 신용카드 - 안심클릭, ISP, 비인증신용카드, 해외 Visa 카드, KPay, 삼성월렛, PayPin 실시간계좌이체 무통장입금 ( 가상계좌 ) 휴대폰결제 포인트 상품권 ( 문화상품권, 해피머니상품권, 스마트문화상품권 ) 전화결제 (ARS) 전자지갑 신용카드빌링 ( 빌링키발급만가능 ) 신용카드 국내또는해외에서발급된모든신용카드를사용하실수있습니다. 해외카드는해외카드이용특약을맺은가맹점에서만사용하실수 있으며, 법인카드및직불형신용카드는할부이용이 불가합니다. ISP( 인터넷안전결제 ) 신용카드사에서인증서를발급받아신용카드번호를입력하지않고본인확인만으로결제하는보다안전한결제방식입니다. 이용금액은신용카드와동일하게청구됩니다. 자세한내용은 http://www.virtualcard.co.kr 을참조하십시오. 실시간계좌이체 인터넷뱅킹과관련된파일, 인증서등이설치된 PC 에서인터넷뱅킹시스템을이용하여계좌이체로지불하는방식이며, 금결원에서제공하는인증창을이용하며, 이용금액은고객의계좌에서실시간으로차감됩니다. 인터넷뱅킹에가입한사용자가각은행의인터넷뱅킹이용 시간에만이용할수있습니다. Page 8
연동가이드작성자최재원검토자강석민 Page 9/55 무통장입금 ( 가상계좌 ) 고객이인터넷쇼핑몰에서물품대금의결제시대금입금을위한은행계좌번호 ( 예금주이니시스 ) 를부여받은후해당가상계좌로물품대금을무통장입금하거나폰뱅킹, PC 뱅킹또는인터넷뱅킹등을이용하여온라인입금하는서비스입니다. (* 입금통보는별도의수신데몬모듈또는수신페이지를사용합니다.) 휴대폰결제 고객이지정한휴대폰으로인증번호를발송하여인증번호를받아소액결제가가능하도록합니다. 결제청구는휴대폰요금에합산되어청구됩니다. ( 통신사마다지정한한도금액이정해있음 ) 포인트결제 OK Cashbag OK 캐쉬백회원이캐쉬백가맹점에서상품또는서비스를구매할때구매금액의일정률을포인트로적립해주며, 상품구매시포인트로결제가가능합니다. OK 캐쉬백카드번호입력후조회된포인트잔액으로단독결제및신용카드복합결제가가능합니다. 포인트결제 삼성 U 포인트 삼성전자회원이삼성전자서비스센터등에서상품또는서비스를구매할때구매금액의일정률을포인트로적립해주며, 상품구매시포인트로결제가가능합니다. 삼성 U 포인트카드번호입력후조회된포인트잔액으로단독결제및신용카드복합결제가가능합니다. 포인트결제 GS 포인트 GS 회원이 GS 계열사등에서상품또는서비스를구매할때구매금액의일정률을포인트로적립해주며, 상품구매시포인트로결제가가능합니다. GS 포인트카드번호입력후조회된포인트잔액으로단독결제및신용카드복합결제가가능합니다. Page 9
연동가이드작성자최재원검토자강석민 Page 10/55 상품권 문화상품권 한국문화진흥원 ( 컬처랜드 ) 에서제공하는문화상품원의아이디결제방식으로컬처랜드에회원으로가입이되어있어야사용이가능합니다. 자세한내용은 http://www.cultureland.co.kr 을참조하십시오. 상품권 도서문화상품권 한국도서보급 ( 북앤라이프 ) 에서제공하는상품권으로상품권번호만으로도결제가가능합니다. 북앤라이프캐시를충전해서 ID 와비밀번호로결제하는방식과사용처에서상품권금액부분을스크래치하여나온 PIN 번호를입력해결제하는방식두가지가있습니다. 상품권번호결제는상품권한장만결제가가능하며, 여러장결제하려는경우아이디결제를이용하여야합니다. 자세한내용은 http://www.booknlife.com 을참조하십시오. 상품권 스마트문화상품권 한국문화진흥원 ( 컬처랜드 ) 에서제공하는상품권으로온라인사용처에서회원가입없이사용이가능하며, 스마트문화상품권번호를입력하여결제할수있습니다. 자세한내용은 http://www.cultureland.co.kr 을참조하십시오. 상품권 옐로페이 옐로페이홈페이지에서회원가입후즉시이용가능하며, 최초 1 회통장및휴대폰번호를등록하고체크카드처럼이용이가능합니다. 결제창에서휴대폰번호만입력후걸려온전화를받은후 5 자리비밀번호를입력하여결제를진행할수있습니다. 자세한내용은 http://www.yelopay.com 을참조하십시오. 상품권 틴캐시 틴캐시의카드번호를직접입력항사용하는방식과틴캐시사이트에서회원가입을통해아이디에충전해사용하는아이디방식이있습니다. 자세한내용은 http://www.teencash.co.kr 을참조하십시오. Page 10
연동가이드작성자최재원검토자강석민 Page 11/55 상품권 해피머니상품권 ( 주 ) 해피머니아이엔씨가발행하는종이형실물상품권으로결제시여러장의해피머니상품권을결제할수있어고액결제가가능합니다. 해피머니회원가입을통해상품권번호를입력하여충전후사용할수있습니다. 자세한내용은 http://www.happymoney.co.kr 을참조하십시오. 전화결제 고객이지정한유선전화로걸려오는전화를받아소액결제가가능하도록합니다. 결제청구는유선전화요금에합산되어청구됩니다. ( 가입자주민번호당월 20 만원한도로이용가능 ) 전자지갑 뱅크월렛 뱅크월렛카카오에서제공하는앱을스마트폰에설치후회원으로가입이되어있어야사용가능합니다. 고객이인터넷쇼핑몰에서제공하는인증번호를휴대폰앱실행후입력하여결제가가능합니다. 자세한내용은 http://www.bankwallet.co.kr 을참조하십시오. 신용카드빌링 ( 정기결제 ) 상점고객이회원제서비스또는월정액과금상품구매요청단계에서, 이니시스가제공하는본인인증서비스수행후전달받은 KEY 를이용하여, 추후해당고객에대한과김이필요시해당 KEY 를이니시스로전송하여실시간으로과금하는서비스. 현재 INIpay Standard 실시간빌링서비스의경우 KEY 발급만가능. 과금의경우기존 TX 사용 이니시스는최초본인인증수행후, 고객의신용카드번호등의결제정보를대체하는빌키를상점에전달하며, 실시간빌링처리를위해상점에서빌키를전달하여야한다. ( 단, 자체가맹점의경우별도협의가필요할수있음 ) 현재 INIpay Standard 실시간빌링서비스의경우신용카드빌링만가능. 신용카드를이용하여매월일정한금액을고객에게청구하는방식이며, 매번번거로운결제절차를생략함으로고객의편의성증대를기대할수있습니다. 자세한내용은 http://www.inicis.com/blog/archives/472# 을참조하십시오. Page 11
연동가이드작성자최재원검토자강석민 Page 12/55 에스크로 구매자의구매의사확인후결제대금을지급하는방식으로 2012 년 08 월 18 일부터의무시행을하고있습니다. 결제방법으로는신용카드, 계좌이체, 가상계좌에적용이가능합니다. 에스크로의배송등록, 거절확인, 현금영수증등은 TX 모듈과연동하여처리합니다. 기존 TX 모듈을그대로활용가능합니다. 자세한내용은 http://www.inicis.com/blog/archives/470 을참조하십시오. Page 12
연동가이드작성자최재원검토자강석민 Page 13/55 1.4 구조와결제처리흐름 INIpay Standard 는다음과작은작업을수행합니다. 1.4.1 결제요청 가맹점에서 SHA256 Hash 를이용하여위변조방지를포함한결제데이터를생성합니다. 결제페이지에서제공되는스크립트를 Import 한후결제요청스크립트를실행하면 스크립트에의해서 form 데이터를 INIpay Standard 로 HTTPS(SSL) Post 액션을발생시켜결제요청데이터로보냅니다. 이니시스는결제요청을받아사용자의디바이스에따른결제창을표시하고사용자가결제 ( 인증 ) 를진행할수있도록합니다. 인증이완료되면인증결과파라미터를가맹점결과페이지로 POST 요청합니다. 수신한인증결과에서인증키 (authtoken) 와 hash 한 signature 를인증결과에함께 수신한승인 API Url(authUrl) 로 HTTPS API request 를통해서승인요청합니다. 리턴된승인결과를가맹점에표시합니다. Page 13
연동가이드작성자최재원검토자강석민 Page 14/55 2. 설치 2.1 설치가능한운영체제 Java, php, asp.net 등 HTTPS 통신이가능한웹서버환경의모든운영체제에서사용이가능합니다. * 다만, 개인용 PC 에서는운영을권장하지않습니다. 2.2 소프트웨어요구사항 Web Server 웹서버 ( 또는웹컨테이너 ) * SHA256 Hash 값의생성 / httpclient(http Background) 통신이가능한웹서버 DBMS 거래내역및처리결과를데이터베이스에저장하길원하신다면, 데이터베이스소프트웨어가별도로필요합니다. * INIpay Standard 는데이터베이스연동작업을위한기능이포함되어있지않습니다. ( 데이터베이스연동을위한지불결과데이터만제공 ). 소스버젼 1. PHP 4.3.4 이상 2. JAVA 1.5 이상 2.3 하드웨어요구사항 일반적인서버운영체제의운용환경에준하며, 특별한하드웨어요구사항은없습니다. Page 14
연동가이드작성자최재원검토자강석민 Page 15/55 2.4 방화벽설정 이용가맹점서버앞에방화벽이있는경우반드시결제승인, 결제취소에대한통신이가능하도록 방화벽설정을해야합니다. 결제인증 연결대상 : https://stdpay.inicis.com 프로토콜 : HTTPS 포트번호 : 443 연결방향 : INBOUND, OUTBOUND 결제승인 연결대상 : https://fcstdpay.inicis.com, https://drstdpay.inicis.com, https://ksstdpay.inicis.com 프로토콜 : HTTPS 포트번호 : 443 연결방향 : INBOUND, OUTBOUND 결제취소 연결대상 : 203.238.37.3, 211.219.96.180, 39.115.212.10 프로토콜 : TCP 포트번호 : 34049, 9102 연결방향 : OUTBOUND Page 15
연동가이드작성자최재원검토자강석민 Page 16/55 2.5 샘플소스 샘플소스는가맹점의환경에맞도록수정하여사용할수있습니다. INIpay Standard 는표준웹통신만을사용합니다. 결제요청시에는페이지이동 (Form POST Action), API 통신시에는 httpclient 통신을이용합니다. * HTTPS API Request(httpClient 통신 ) = httpclient 등의 http Background 통신이가능한유틸을통해서웹페이지를요청후그결과를수신 본샘플소스에는통신에대한별도의로그 (Log) 기능이존재하지않습니다. 가맹점에서환경에맞게로그를개발하시기바랍니다. INIStdPayRequest.xxx INIStdPayBill.xxx 결제요청샘플페이지 신용카드빌링샘플페이지 주요연동파일설명 popup.xxx 결제창을팝업으로표시할때사용 ( 권장하지않음 ) close.xxx 결제창 ( 팝업, 오버레이 ) 을닫을때사용 ( 수정금지 ) INIStdPayReturn.xxx INIStdCancel.xxx 결제인증결과수신 / 승인요청 API 연동샘플페이지 결제취소페이지 Page 16
연동가이드작성자최재원검토자강석민 Page 17/55 2.5.1 Java INIStdweb_JAVA.zip 의압축을풀어설치합니다. 이때설치절대경로를확인합니다. INIStdweb 결제연동프로그램은다음과같이파일과디렉터리가생성됩니다. WenContent 이하소스를웹 Root 아래넣고이를참고해결제모듈을연동합니다. INIpay50.jar : 취소및일부서비스에서사용하는 library 로 INIpay 암복호화파일. [WEB-INF/lib/] INIpay_Sample_v1.3.jar : 해당라이브러리는샘플페이지구동을위한라이브러리로참고만부탁드리며, 실제반영시엔가맹점환경에맞게직접생성부탁드립니다. ** 샘플라이브러리만을이용하여연동시, 가맹점환경에따른오작동은당사확인이어려울수있습니다. ExecureCrypto_v1.0_jdk14.jar : 웹서버가기동되는순간참조하는웹서버라이브러리 classpath 경로에 설치합니다. 예 ) tomcat/shared/lib 위치, 또는 jdk /jre/lib/ext 위치에옮김 key : 각종키파일이위치합니다. 이파일들은데이터암복호화및서명에사용됩니다. log : 날짜별로그가저장되는폴더입니다. log 로쓰기권한을주시기바랍니다. 결제시는웹로그를 통해확인가능하며, 취소시 TX 서버의로그가기록됩니다. INIStdpaySample : HTML, JSP Sample 이위치하는폴더입니다. Page 17
연동가이드작성자최재원검토자강석민 Page 18/55 2.5.2 ASP.net INIStdweb_ASP.zip 의압축을풀어설치합니다. 이때설치절대경로를확인합니다. INIStdweb 결제연동 프로그램은다음과같이파일과디렉터리가생성됩니다. INIcrypto.dll, INIpayNet.dll, INIpay50.dll : 암복호화에사용하는 dll 파일 Page 18
연동가이드작성자최재원검토자강석민 Page 19/55 2.5.3 ASP INIStdweb_ASP_Sample_v1.x.zip 의압축을풀어설치합니다. 이때설치절대경로를확인합니다. INIStdweb 결제연동프로그램은다음과같이파일과디렉터리가생성됩니다. function 기본제공함수 signature 위변조방지체크기능의 signature 생성 Page 19
연동가이드작성자최재원검토자강석민 Page 20/55 2.5.4 PHP libs : INIpay 암복호화및결제에서사용하는 library 파일. INIStdPaySample : HTML, PHP Sample 이위치하는폴더입니다. key : 각종키파일이위치합니다. 이파일들은데이터암복호화및서명에사용됩니다. Log : 날짜별로그가저장되는폴더입니다. log 로쓰기권한을주시기바랍니다. 결제시는웹로그를 통해확인가능하며, 취소시 TX 서버의로그가기록됩니다. Page 20
연동가이드작성자최재원검토자강석민 Page 21/55 2.6 파일 / 디렉터리권한 Window 계열운영체제는 IUSR_HOSTNAME 이라는계정이존재합니다. 아래와같이권한을조정해주십시오. 해당폴더선택, 마우스오른버튼클릭후 등록정보 (XP 는 속성 )-> 보안 탭 설치경로 /key 와 /log 하위폴더 / 파일 - IUSR_HOSTNAME 이접근 / 읽기 / 쓰기권한을가지도록조정 UNIX/LINUX 계열운영체제는다음과같은접근권한을설정을합니다. 설치경로 /key 와 /log 하위폴더 / 파일 - Chmod R 777 key(log) 접근 / 읽기 / 쓰기권한을가지도록조정 설치 Directory 는절대 Web 으로접근할수있는경로에설치하지마십시오. Sample 폴더가 Web 접근폴더에위치하는것은관계없으나, 그외폴더 (key,log) 는보안상절대 Web 을통해서접근하도록허용하지마십시오. 그리고 key 와 log 디렉터리는동일한경로에위치하도록설정합니다. 예 ) www 폴더하위, public_html 폴더하위 Page 21
연동가이드작성자최재원검토자강석민 Page 22/55 2.7 승인테스트 1 웹브라우저에서 http://127.0.0.1/inistdpaysample/inistdpayrequest.xxx 페이지를호출합니다. - Ie11 의경우 localhost 로진행할경우팝업창의문제가발생할수있음 2 승인테스트를위해필수값및기본옵션값을매뉴얼을참조후확인후결제요청버튼을누릅니다. 3 설치과정없이지불방법을선택후필요한정보를기입하고 확인 을눌러진행합니다. ( 해당사이트팝업을사용으로하지않을시초기화면으로로딩될수있습니다. ) 4 지불과정중필요에따라추가적인모듈을다운로드하는경우도있습니다. 정상적으로지불결과메시지가나타나는지확인하십시오. 취소 / 조회테스트를위해거래번호 (TID) 를기록해두십시오. Page 22
연동가이드작성자최재원검토자강석민 Page 23/55 3. 결제연동 3.1 결제요청페이지작성 (INIStdPayRequest) 3.1.1 결제요청데이터 내부처리용데이터별도저장 form 데이터처리가필요한경우페이지표시전에별도로 DB 또는세션등에저장해두시기바랍니다. signkey 값설정 웹표준결제이용시패스워드기능을하는코드로 MID 번호별로부여됩니다. String mid = "INIpayTest"; // 가맹점 ID( 가맹점수정후고정 ) // 가맹점에제공된웹표준사인키 ( 가맹점수정후고정 ) String signkey = "SU5JTElURV9UUklQTEVERVNfS0VZU1RS"; signkey 발급방법 관리자페이지의상점정보 > 계약정보 > 부가정보의웹결제 signkey 생성조회버튼클릭후 팝업창에서생성버튼클릭후해당값소스에반영하시기바랍니다. 표준결제스크립트 Import - 실서버 ( 실반영시반드시수정 ) <script language="javascript" type="text/javascript" src="https://stdpay.inicis.com/stdjs/inistdpay.js" charset="utf-8"></script> - 테스트용도 (INIpayTest 결제테스트가능지불수단별거래승인됨 ) * 신용카드 : 별도의취소를하지않는경우당일 23 시에일괄취소처리됨 * 계좌이체 : 별도의취소를하지않는경우당일 23 시에일괄취소처리됨 * 휴대폰 : 별도의취소를하지않은경우당일 23 시에일괄취소처리됨 * 가상계좌 : 입금테스트진행하도록안내리얼입금의경우환불이어려움 - 테스트서버연동 ( 샘플로제공되는테스트 MID 전용으로상용 MID 사용불가 ) <script language="javascript" type="text/javascript" src="https:/stgstdpay.inicis.com/stdjs/inistdpay.js" charset="utf-8"></script> <head> Tag 안에설정 * 페이지인코딩에관계없이고정 charset="utf-8"( 실테스트용구분후사용 ) Page 23
연동가이드작성자최재원검토자강석민 Page 24/55 <head>. <script language="javascript" type="text/javascript" src="https://stdpay.inicis.com/stdjs/inistdpay.js" charset="utf-8"></script>. </head>. Iframe, Popup 사이즈 - iframe 의경우 width:800px; height=550px; - popup 의경우 ( 팝업사용을권장하지않음 ) width=750px;height=500px Popup 허용여부체크기능 - 팝업허용설정이안되어있을경우, 가맹점의요청페이지가허용시리프레시됨으로, 로딩 완료후가팝업을띄워주는기능 - <body... onload="inistdpay.allowpopup();"> 추가 INIStdpay.pay 함수호출 - INIStdpay.pay 함수호출은 submit 이아닌단순 action 형태로진행 Form 에결제요청데이터생성 - Form Tag 에 ID 설정 ( 결제요청스크립트실행시사용됨 ) - 필드명대소문자구분 ( 일부가맹점에서필요에의해사용자가변경하는경우를제외하고모두 type= hidden 을사용 ) * 아래요청데이터 / Sample Source 를참조 <form id=" SendPayForm_id" name="sendpayform_name" method="post"> <input type= hidden name= mid value= INIpayTest /> <input type= hidden name= price value= 1004 />.. </form> INIpay Standard 는 Form Post 로결제요청되며, <form> 태그에 action 속성설정 / submit 등의 모든동작은 Import 된스크립트에의해서자동처리됩니다. Page 24
연동가이드작성자최재원검토자강석민 Page 25/55 결제인증기본요청데이터필드는아래와같습니다. [TABLE 1-1] 기본요청데이터필드 필드명 한글명칭 예시 [Data Type, 밑줄은기본값 ] 설명 필수 여부 크기 ( 최대 ) version 버전 [String]"1.0" [1.0] 전문버전 Yes 20 Byte mid 상점아이디 [String] "INIpayTest" 제공된 mid * 10 자리고정 Yes ( 위변조검 증 ) 10 Byte Fixed oid 주문번호 [String] INIpayTest 1335233672723 주문단위 unique 한값 ( mid+ _ +timestamp ) Yes 40 Byte goodname 상품명 [String] 키보드 / 마우스 한글 / 특수기호입력가능 * 40Byte 초과요청시 37Byte+ 으로자동변환 Yes 40 Byte price 결제금액 [Number] 1004 숫자만입력 1달러는 100으로시작 Yes ( 위변조검증 ) 64 Byte 숫자만입력 tax 부가세 [Number] 1004 대상 : 부가세업체정함 설정업체에한함주의 : 전체금액의 10% 이하로설정가맹점에서등록시 VAT 가총 No 64 Byte 상품가격의 10% 초과할경우는거절됨 taxfree 비과세 [Number] 1004 숫자만입력대상 : 부가세업체정함 설정업체에한함과세되지않는금액 No 64 Byte currency 통화구분 [String] "WON" [WON: 한화,USD: 달러 ] * USD 는카드결제만가능 (ISP 는 결제안됨 ) Yes 3 Byte buyername 구매자명 [String] " 홍길동 " 한글 / 특수기호입력가능 * 30Byte 초과요청시 27Byte+ 으로 자동변환 Yes 30 Byte buyertel 구매자 Mobi le 번호 [String] 010-2000-1234 숫자와 "-" 만허용 Yes 20 Byte buyeremail 구매자 Email [String] "buyer@example.com" 이메일형식에맞도록 No 60 Byte Page 25
연동가이드작성자최재원검토자강석민 Page 26/55 parentemail 보호자 Email [String] "parent@example.com" 14 세미만필수 60 Byte timestamp 타임스탬프 [Number] 1335233672723 TimeInMillis(Long 형 ) 제공라이브러로 생성가능 ( 샘플소스참조 ) Yes ( 위변조검 증 ) 20 Byte [String]"8ca9e064777ea2fc0d4 위변조방지 SHA256 Hash 값 64 signature signature b79a5c891f3bdf30edd45c129d cfc226ba5e7e85cd5f3" 아래 [TABLE 1-2] signature 생성대상 (Target) 필드 참조 Yes Byte Fixed returnurl 리턴Url ( 인증결과수신Url) [String] "HTTPS://www.exsample.com/I NIpayStandardSample/INIpayR esult.jsp 결제창을통해인증완료된결과를수신받고승인요청을해서결과를표시할페이지 URL 3.3 리턴페이지 ( 인증수신 / 승인API) 작성 (INIStdPayReturn) 참조 Yes N/A mkey signkey 에 대한 hash 값 [String] 3a9503069192f207491d4b19 bd743fc249a761ed94246c8c42 fed06c3cd15a33 signkey 에대한검증값 Yes N/A gopaymeth od 요청결제수단 [String] Card 별첨 A.1. 결제수단코드 참조 하나의결제수단만을제공할경우사용함. 생략시전체결제수단표시 No N/A [String] 20130101-20130331 offerperiod 제공기간 [Y2: 년단위결제, M2: 월단위결제, yyyymmdd- 가맹점에서판매상품에대한제공기한설정 No N/A yyyymmdd : 시작일 - 종료일 ] languagevie w 초기표시언어 [String] ko [ko: 한국어, en: 영어 ] 결제창표시언어 * PC는결제창내언어변경버튼존재 No 2Byt e charset 결과인코딩 [String] UTF-8 [UTF-8, EUC-KR] 결과수신 charset No 5Byt e payviewtyp e 결제창표시방법 [String] [overlay] Default:overlay No N/A closeurl 결제창닫기처리Url [String] "HTTPS://www.exsample.com/i nipaysmart/close.jsp close.jsp 샘플사용 ( 소스수정불필요 ) Yes N/A popupurl 팝업처리 Url [String] "HTTPS://www.exsample.com/i nipaysmart/popup.jsp popup.jsp 샘플사용 ( 소스수정불필요 : 비권장 ) Yes N/A merchantda ta 가맹점데이 터 [String] a=a&b=b 인증성공시가맹점으로리턴 No 1000 Byte Page 26
연동가이드작성자최재원검토자강석민 Page 27/55 acceptmeth od acceptmeth od [String]CARDPOINT:va_receipt:v bank(20150425):va_ckprice:skin( ORIGINAL):FONT(ORIGINAL) 결제수단별추가옵션값 No N/A Page 27
연동가이드작성자최재원검토자강석민 Page 28/55 기본요청데이터의 signature 필드의구성은다음과같습니다. [TABLE 1-2] signature 생성대상 (Target) 필드 필드명한글명칭예시비고필수여부 oid 주문번호 INIpayTest 1335247243 103 Yes price 가격 10000 가맹점주문번호 / 결제단위 Unique Yes timestamp 타임스탬프 1335247243103 TimeInMillis(Long) Yes 밀리세컨드타임스템프를 Long 형으로변환 한숫자 * 제공라이브러리로생성가능 Signature 생성방법은아래의 [3.3 signature 생성 ] 참조 기본요청데이터외에다음과같이결제수단별로옵션값을추가하여결제요청할수있습니다. [TABLE 1-3] 신용카드추가요청필드 ( 선택 ) 필드명하위필드한글명칭예시 설명 quotabas e [Data Type, 밑줄은기본값 ] 할부개월 [String] 2:3:4, 2:0 * 개월수를 : 로구분된값 일시불은기본적을표시, 생략시일시불만 * 5 만원이상시에만동작 nointerest 가맹점부 [String] 11-2:3:5:6,34-2:6, * 5 만원이상시에만동작 / 카드사무이자와무관 담무이자 할부설정 04-2:6 * 카드사코드-할부개월 : 할 별첨 A2 카드사코드 참조 부개월 여러카드는공백없이, 로 구분 acceptme thod below100 1000원이하 [String] " below1000 기본적으로 1000원이하결제불가능 0 결제 mallpoint 몰포인트 [String] mallpoint(14:03) 상점에서따로카드사와포인트계약을맺은경우에대한처리이다. ':' 구분자로카드코드를구분한다. ini_onlyca 결제 카드 [String]"1:2:3:4:6 생략시결제가능한모든카드사표시 rdcode 사선택 [ 카드사코드 별첨 A2 카드사코드 참조 Page 28
연동가이드작성자최재원검토자강석민 Page 29/55,VCARD: ISP 카드사,ACARD: 안심클릭카드사,NCARD: 비인증카드사 ] CARDPOI NT 카드포인트사용유무 OCB OCB 사용 유무 SLIMQUO 부분무이자 TA 설정 PAYPOP 안심클릭 UP 뷰옵션 hidebar 프로그래스 바뷰옵션 useescro 신에스크로 w 사용여부 * 카드사코드를 : 로구분된값 cardpoint ocb [String] SLIMQUOTA (14:03) [String] PAYPOPUP [String] hidebar [String] useescrow 포인트를사용하는카드를선택시신용카드메인화면에카드포인트를사용할지에대한선택창이표시된다. 카드메인화면에 OCB 적립을위한카드번호창이표시된다. 기준정보에서 OCB 옵션을받은경우에만정상동작한다. OK Cashbag 포인트적립을가능하도록체크박스가나타난다. 슬림할부를지정한다. SLIMQUOTA( 코드-개월 : 개월 ) 로사용한다. '^' 구분자로카드코드를구분한다. 안심클릭을 Popup 형태로서비스를제공한다. Edge의경우자동설정됩니다. 결제진행시노출되는프로그래스바를안보이도록설정된다. 신에스크로약관동의 와 구매자본인확인 페이지가포함된신에스크로결제창을호출합니다. [TABLE 1-4] 계좌이체추가요청필드 ( 선택 ) 필드명하위필드한글명칭예시 설명 [Data Type, 밑줄은기본 값 ] acceptme thod no_receip t 현금영수증 미발행 [String] no_receipt 현금영수증발행차단옵션 계좌이체시사용하는현금영수증미발행여부확인 필드 옵션을사용시현금영수증 UI 출력하지않음 [TABLE 1-5] 무통장입금추가요청필드 ( 선택 ) 필드명하위필드한글명칭예시 설명 [Data Type, 밑줄은기본값 ] INIregno 주민번호설정기능 [String] 201504161111111 13자리 ( 주민번호 ),10자리( 사업자번호 ), 미입력시 ( 화면에서입력가능 ) acceptme thod vbank 입금기한및입금시간 ( 초설.[String] vbank(20150416) 입금기한및입금시간설정옵션 EX) vbank(20170224) 또는 vbank(201702241900) 시분까지지정 Page 29
연동가이드작성자최재원검토자강석민 Page 30/55 정불가 ) va_receipt 현금영수증발급 UI 옵션 [String] va_receipt 현금영수증발급 UI 표시옵션 (CASHRECEIPT 옵션이 기준정보에있는경우 ) 주민번호만표시 va_ckprice 주민번호채번시금액확인 [String] va_ckprice 주민번호채번시금액체크기능 [TABLE 1-6] 휴대폰추가요청필드 ( 선택 ) 필드명하위필드한글명칭예시 설명 [Data Type, 밑줄은기본 값 ] acceptme thod HPP 휴대폰결 제상품유 형 [String] HPP(1) [1: 컨텐츠,2: 실물 ] 휴대폰결제상품유형 [TABLE 1-7] 전자지갑 [ 뱅크월렛 ] 추가요청필드 ( 선택 ) 필드명하위필드한글명칭예시 설명 gopaym ethod KWPY_TY PE [Data Type, 밑줄은기본값 ] 결제구분 [String] "0" [0: 현금카드와뱅크머니모두, 1: 현금카드만, 2: 뱅크머니만 ] KWPY_VA T 부가세, 봉사료 [String] "10 0" [vat_type 0: 과세, 1: 면세, 2: 업체정함 ] vat_type : 2 일때만 10 0 이사용됨 * 부가세와봉사료를 로구분된값 [TABLE 1-8] 빌링추가요청필드 ( 선택 ) 필드명하위필드한글명칭예시 설명 acceptm ethod [Data Type, 밑줄은기본값 ] BILLAUTH 빌링결제구분 [String] "BILLAUTH(card)" 신용카드빌링결제를제공한다. Page 30
연동가이드작성자최재원검토자강석민 Page 31/55 3.2 실시간신용카드빌링서비스작성 (INIStdPayBill) 3.2.1 실시간빌링서비스조건 1. 반드시실시간빌링서비스업체로당사에등록 2. 실시간빌링가능카드 (2016 년 8 월기준 ) - 롯데, 삼성, 신한, 현대, 국민, 비씨 NH, 하나 SK, 씨티 - 당사는씨티카드와직접적인가맹점계약인되어있지않음 3. 신용카드본인인증트랜잭션처리후전달받은 BillingKey 를실시간빌링요청 (TX 사용 ) 시전송해야만빌링가능. - BillingKey 를이용한실시간빌링요청은 TX 모듈과연동하여처리합니다. 기존 TX 모듈을그대로활용가능합니다. 3.2.2 빌링키발급테스트 빌링가능한 mid 설정 String mid = " INIBillTst"; // 가맹점 ID( 가맹점수정후고정 ) // 가맹점에제공된웹표준사인키 ( 가맹점수정후고정 ) String signkey = "SU5JTElURV9UUklQTEVERVNfS0VZU1RS"; [ 신용카드빌링요청필드 ] 필드명하위필드한글명칭예시 설명 [Data Type, 밑줄은기본값 ] acceptmethod BILLAUTH 빌링결제구분 [String] "BILLAUTH(card)" 신용카드빌링결제를제공한다. [ 휴대폰빌링요청필드 ] 필드명하위필드한글명칭예시 설명 [Data Type, 밑줄은기본값 ] acceptmethod BILLAUTH 빌링결제구분 [String] BILLAUTH(HPP):HPP(4)" 이니시스와계약한빌링방법 이컨텐츠인경우 [String] BILLAUTH(HPP):HPP(5)" 이니시스와계약한빌링방법 이실물인경우 제공기간 (ini_offer_period) 상세설정안내 - 월자동결제표시 M2, m2 예 ) <input type=hidden name=ini_offer_period value="m2" /> Page 31
연동가이드작성자최재원검토자강석민 Page 32/55 - 연자동결제표시 Y2, y2 예 ) <input type=hidden name=ini_offer_period value="y2"/> - 24 시간표시 T2, t2 예 ) <input type=hidden name=ini_offer_period value="t2"/> [ 신용카드빌링결과필드 ] 필드명 한글명칭 Data Type 설명 크기 ( 최대 ) CARD_BillKey 빌링키 String Billing 트랜잭션을위한기본 key (40자리) 40 Byte [ 휴대폰빌링결과필드 ] 필드명 한글명칭 Data Type 설명 크기 ( 최대 ) HPP_BillKey 빌링키 String Billing 트랜잭션을위한기본 key (40자리) 40 Byte HPP_Num 휴대폰번호 String 휴대폰번호 14 Byte 3.3 에스크로결제 웹표준결제 (INIpay_Standard) 는에스크로결제및구매확인만지원합니다. 배송등록, 결제취소, 거절확인, 현금영수증페이지는 TX5( 이니에스크로 ) 모듈로진행되므로 INIpay_V.5.0_INIescrow 매뉴얼 ( 언어별 ) 과함께참고하여개발진행부탁드립니다. (2016.09.29 기준 ) 3.3.1 에스크로결제요청연동 (INIstdPayRequest) 3.1 참조하여결제페이지작성 신용카드, 실시간계좌이체, 무통장입금 ( 가상계좌 ) 신에스크로서비스의경우에스크로서비스를이용하시려면 결제요청페이지 (INIstdPayRequest.xxx) 안에 accepmethod 의 value 를 useescrow 로추가하셔야합니다. 값을추가하지않을경우일반 결제로진행됩니다. ( 값을고정으로할경우일반 / 에스크로고정으로 발생. 사용자선택사항 - check box 등 - 으로제공시사용자가선택한 방법으로결제진행 ) 예 ) <input type=hidden name=acceptmethod value="skin(original):hpp(1): useescrow "> Page 32
연동가이드작성자최재원검토자강석민 Page 33/55 3.3.2 에스크로구매확인연동 (INIescrow_confirm) 에스크로샘플에서만제공합니다.( 웹표준결제샘플미제공 ) 이니에스크로구매확인은고객이결제를완료하고, 배송등록이이뤄진상태에서설정가능하며, 구매자가구매확정또는구매거절을선택합니다. 매매보호서비스에서소비자가구매확정은반드시필요한기능입니다. [ 구매확인요청필드 ] 필드명 한글명칭 예시 [Data Type, 밑줄은기본값 ] 설명 필수여부 크기 ( 최대 ) version 버전 [String]"1.0" [1.0] 전문버전 Yes 20 Byte mid 상점아이디 [String] "INIpayTest" 제공된 mid * 10자리고정 Yes 10 Byte Fixed tid 거래번호 [String] StdpayCARDiniescrow0201609291 00142221570 승인성공시응답받은거래번호 Yes 40 Byte currency 통화 [String] "WON" [WON: 한화,USD: 달러 ] * USD는카드결제만가능 (ISP는결제안됨 ) Yes 3 Byte timestamp 시간변환 [Number] 1335233672723 TimeInMillis(Long 형 ) 제공라이브러로 생성가능 ( 샘플소스참조 ) Yes 20 Byte [String] mkey 암호화키 3a9503069192f207491d4b19bd7 43fc249a761ed94246c8c42fed06c signkey 에대한검증값 Yes N/A 3cd15a33 charset 인코딩 [String] UTF-8 [UTF-8, EUC-KR] 결과수신 charset No N/A payviewtype 결제창표시방법 [String] default = ovelay overlay 결제호출방식을결정 No N/A returnurl 응답 URL [String] "HTTPS://www.exsample.com/inip aysmart/ INIStdPayReturn.jsp 구매확인또는거절후결과 전문을받기위한 URL Yes N/A closeurl 결제창 닫기처리 Url [String] "HTTPS://www.exsample.com/inip 결제창을닫기위한 URL No N/A Page 33
연동가이드작성자최재원검토자강석민 Page 34/55 aysmart/close.jsp popupurl 팝업처리 Url [String] "HTTPS://www.exsample.com/inip aysmart/popup.jsp 결체창팝업진행시사용하는 URL ( 비권장 ) No N/A [ 구매확인응답필드 ] 필드명 설명 ResultCode 처리결과코드. ResultMsg 처리결과내용. 상세코드표시. CNF_Date CNF_Time DNY_Date DNY_Time 구매확정일경우, 처리일자. 형식은 YYYYMMDD 구매확정일경우, 처리시각. 형식은 hhmmss 구매거절일경우, 처리일자. 형식은 YYYYMMDD 구매거절일경우, 처리시각. 형식은 hhmmss 3.4 리턴페이지 ( 인증수신 / 승인 API) 작성 (INIStdPayReturn) * 작성시 Sample Source 를참고하여작성하시기바랍니다. 3.4.1 인증결과수신 결제창을통해인증이완료되면인증결과를가맹점으로전달합니다. 인증결과데이터필드는아래와같습니다. [TABLE 2-1] 인증결과데이터 필드명한글명칭 Data Type 설명 크기 ( 최대 ) resultcode 결과코드 String [0000 : 정상, 기타 : 실패 ] 10 Byte resultmsg 결과메세지 String 성공시 : OK, 실패시 : 기타오류메시지 100 Byte mid 가맹점 ID String 가맹점 ID 10 Byte ordernumber 가맹점주문번 호 String 가맹점주문번호 40 Byte authtoken 승인요청 String 승인요청검증토큰 authurl 승인요청 Url String 해당 URL 로 HTTPS API Request(httpClient 통신 ) 승인요 청 (POST) Page 34
연동가이드작성자최재원검토자강석민 Page 35/55 netcancelurl 망취소요청 Url String 승인요청후인증결과수신실패 / DB 저장실패시 해당 URL 로 HTTPS API Request(httpClient 통신 ) 승인요 청 (POST) charset 인증결과인코 딩 String 가맹점에서결제요청시전달한 charset 값생략시 UTF-8 5 Byte merchantdata 가맹점데이터 String 가맹점관리데이터 1000Byte 3.4.2 승인 API 요청 인증결과가성공일때 authurl 로 HTTPS API Request(httpClient 통신 ) 를통해페이지요청 * HTTPS API Request(httpClient 통신 ) = httpclient 등의 http Background 통신이가능한유틸을통해서웹페이지를요청후그결과를수신 가맹점환경에따른 charset, format 을지정하여요청 승인요청은인증결과리턴후 5 분이내이루어져야만합니다. 결제승인요청데이터는필드는아래와같습니다. [TABLE 2-2] 승인요청데이터 필드명한글명칭예시 설명 필수 크기 [Data Type, 밑줄은기본값 ] 여부 ( 최대 ) mid 가맹점 id [String] INIpayTest 가맹점아이디 Yes 10 Byte fixed authtoken 인증 [String] 인증결과에대한위변조검증값 Yes -- 결과코드 sgnwsy9uz3c9lbkjitgip4vdd 5L+dM0+dmuv+R707vExQC5 XjwjSCUOa/QumiTMW ( 위변조 검증 ) Y8+aLvjFu. price 인증가격 1000 인증가격결과에대한위변조확인용 Yes ( 가격 64 Bytes timestamp 타임스템프 [Number] 1335233672723 TimeInMillis(Long 형 ) 제공라이브러로 생성가능 ( 샘플소스참조 ) 위변조검증 ) Yes ( 위변조검증 ) 20 Byte Page 35
연동가이드작성자최재원검토자강석민 Page 36/55 signature signature [String] 11f65eea829cc2c165874b104 dbfd4965fc30d5ef9292405413 bb8504cc5997d charset 리턴인코딩 [String] EUC-KR [UTF-8, EUC-KR] format 리턴형식 [String] JSON [XML, JSON, NVP] 위변조방지 SHA256 Hash 값 * 결제요청동일한방법으로 signature와생성 [TABLE 2-3] 승인요청 signature 생성대상 (Target) 필드 참조결과수신 charset 결과수신형태 XML : <result> 내의 XML 결과리턴 JSON : root 없이 json 결과리턴 NVP : name=value&name=value 으로결과리턴 [TABLE 2-13] 리턴형식별승인결과예시 참조 Yes 64 Byte 5 Byte 5 Byte Page 36
연동가이드작성자최재원검토자강석민 Page 37/55 결제승인요청데이터의 signature 필드의구성은다음과같습니다. [TABLE 2-3] 승인요청 signature 생성대상 (Target) 필드 필드명한글명칭예시비고필수 여부 authtoken 인증결과수신후생성된토큰 sgnwsy9uz3c9lbkjitgip 인증결과수신한 authtoken Yes 값 4VdD5L+dM0+dmuv+ R707vExQC5XjwjSCUOa /QumiTMW Y8+aLvjFu. timestamp 타임스탬프 1335247243103 TimeInMillis(Long) Yes 밀리세컨드타임스템프를 Long 형으로 변환한숫자 * 제공라이브러로생성가능 Target 데이터예시 : authtoken=sgnwsy9uz3c9lbkjitgip4vdd5l+dm0+dmuv+r707vexqc5xjwjscuoa/it Signature 생성방법은아래의 [3.3 signature 생성 ] 참조 3.4.3 승인 API 결과 ( 결제완료 ) 승인요청후결제결과 (responsebody) 를받아요청타입 (format) 에따라서파싱후에내부처리 (DB 저장등 ) 하시기바랍니다. 수신시전송필드명을명확히하여처리하시기바랍니다. ( 필드명대 / 소문자구분 ) 승인에실패하였을경우실패시전달되는데이터만전송됩니다. 결제수단에따라공통필드외추가적으로다른데이터가전송됩니다. 승인결과데이터필드는아래와같습니다. [TABLE 2-4] 승인결과데이터 ( 공통 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) tid 거래번호 String 거래번호 40 Byte Page 37
연동가이드작성자최재원검토자강석민 Page 38/55 resultcode 결과코드 String [0000 : 정상, 기타 : 실패 ] 10 Byte 승인결과코드참조 resultmsg 결과메세지 String 결과메세지 100 Byte EventCode 이벤트코드 String 카드할부및행사적용코드. 3 Byte [ 별첨정보참조 ] TotPrice 거래금액 String 결제결과금액 20 Byte MOID 주문번호 String 상점주문번호. 결제요청시 "oid" 필드에설정된값 12 Byte paymethod 지불수단 String 결제방법 10 Byte applnum 승인번호 String 결제수단에따리미전송 16 Byte appldate 승인일자 String YYYYMMDD 8 Byte appltime 승인시간 String hh24miss 6 Byte 결제수단에따라승인결과가추가로수신됩니다. 데이터는다음과같습니다. [TABLE 2-5] 승인결과데이터 ( 신용카드 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) CARD_Num 신용카드번호. String 신용카드번호. 16 Byte CARD_Intere st 할부여부 String 카드할부여부. ( 1 이면무이자할부 ) 1 Byte CARD_Quota 카드할부기간. String 카드할부기간. 2 Byte CARD_Code 카드사코드. [ 별첨정보참조 ] String 카드사코드. [ 별첨정보참조 ] 2 Byte CARD_PRTC_ CODE 부분취소가능여 부 String 부분취소가능여부 (1: 가능, 0: 불가능 ) 1 Byte CARD_BankC ode 카드발급사 String 카드발급사 ( 은행 ) 코드. [ 별첨정보참조 ] 카드사직발행카드가아닌계열카드인경우, 2 자리신용카드사코드와더불어자세한카드정보를나타냅니다 ( 직발행카드인경우 00 으로반환됩니다 ). 2 Byte Page 38
연동가이드작성자최재원검토자강석민 Page 39/55 < 예 > CARD_Code 가 11, CARD_BankCode 가 23 인경우 제일은행에서발급한 BC 카드 currency 통화코드 String 달러결제정보, 통화코드. 3 Byte OCB_Num OCB_SaveAp plnum OCB_PayApp lnum OCB_ApplDa te OCB_PayPric e OK CASHBAG 카드번호 OK CASHBAG 적립승인번호 OK CASHBAG 사용내역승인번호 OK CASHBAG 승인일시 OK CASHBAG 포인트지불금액 String OK CASHBAG 적립및사용내역, 카드번호 20 Byte String OK CASHBAG 적립및사용내역, 적립승인번호 12 Byte String OK CASHBAG 적립및사용내역, 사용승인번호 12 Byte String OK CASHBAG 적립및사용내역, 승인일시 8 Byte String OK CASHBAG 적립및사용내역, 포인트지불금액 12 Byte [TABLE 2-6] 승인결과데이터 ( 계좌이체 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) ACCT_BankC ode 은행코드 String 은행코드, [ 별첨정보참조 ] 2 Byte CSHR_Result Code 현금영수증발행 정상여부 String 현금영수증, 발급결과코드 10 Byte CSHR_Type 현금영수증구분 String 현금영수증, 발급구분코드 1 Byte [TABLE 2-7] 승인결과데이터 ( 무통장 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) VACT_Num 입금계좌번호. String 무통장입금가상계좌번호 20 Byte VACT_BankCo de 입금은행코드. String 별첨 A4 은행코드 참조 2 Byte vactbankname 입금은행명 String 무통장입금은행명 20 Byte Page 39
연동가이드작성자최재원검토자강석민 Page 40/55 VACT_Name 예금주명. String 예금주명 20 Byte VACT_InputNa me 송금자명. String 입금시고객명 20 Byte VACT_Date 송금일자. String 송금일자 8 Byte VACT_Time 송금시각. String 송금시각 6 Byte [TABLE 2-8] 승인결과데이터 ( 휴대폰결제 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) HPP_Num 휴대폰번호 String 휴대폰번호 14 Byte paydevice 결제장치 String PC 6 Byte [TABLE 2-9] 승인결과데이터 ( 포인트 ) 필드명한글명칭 Data 설명 크기 필드명 Type ( 최대 ) PayOption 지불구분 String OCBpay/OCBplus/OCBpayonly/OCBbot h/gsptpay 10 Byte 포인트사용구분 OCB_Num OCB_PayPri ce UPoint_Nu m UPoint_usa blepoint UPoint_App lprice UPNT_Pay Option UPNT_Save Price OCB 카드번호 OCB 지불금액 U포인트카드번호 U포인트가용포인트 U포인트승인요청금액 U포인트지불구분 U포인트여신승인금액 String OK CashBag 카드번호 20 Byte OCB String OK CashBag 지불금액 12 Byte String U포인트카드번호 16 Byte U 포인트 String U포인트가용포인트 12 Byte String U포인트승인요청금액 12 Byte String U포인트지불구분 10 Byte U 포인트 String U포인트복합결제시여신승인금액 16 Byte UPNT_Pay U 포인트지 String U 포인트지불금액 9 Byte Page 40
연동가이드작성자최재원검토자강석민 Page 41/55 Price GSPT_ApplP rice GSPT_SaveP rice GSPT_PayPri ce 불금액 GS 포인트승인금액 GS 포인트적립금액 GS 포인트지불금액 String GS포인트승인금액 15Byte GS 포인트 String GS포인트적립금액 15Byte String GS포인트승인금액 15Byte [TABLE 2-10] 승인결과데이터 ( 상품권 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) CULT_UserID 컬쳐랜드고객 ID String 문화상품권컬쳐랜드고객아이디 20 Byte 필드명한글명칭 Data Type 설명 크기 ( 최대 ) GAMG_Cnt 사용한카드개수 String 스마트문화상품권사용한카드개수 1 Byte GAMG_ApplPri ce 게임문화상품권 승인금액 String 스마트문화상품권승인금액 12 Byte GAMG_Num1 카드번호1 String 스마트문화상품권카드번호 18 Byte GAMG_Price1 카드결제금액1 String 스마트문화상품권카드결제금액 12 Byte GAMG_Num2 카드번호2 String 스마트문화상품권카드번호 18 Byte GAMG_Price2 카드결제금액2 String 스마트문화상품권카드결제금액 12 Byte GAMG_Num3 카드번호3 String 스마트문화상품권카드번호 18 Byte GAMG_Price3 카드결제금액3 String 스마트문화상품권카드결제금액 12 Byte GAMG_Num4 카드번호4 String 스마트문화상품권카드번호 18 Byte GAMG_Price4 카드결제금액4 String 스마트문화상품권카드결제금액 12 Byte GAMG_Num5 카드번호5 String 스마트문화상품권카드번호 18 Byte GAMG_Price5 카드결제금액5 String 스마트문화상품권카드결제금액 12 Byte GAMG_Num6 카드번호6 String 스마트문화상품권카드번호 18 Byte GAMG_Price6 카드결제금액6 String 스마트문화상품권카드결제금액 12 Byte TEEN_ApplPric e 틴캐시승인금액 String 지불수단별결제승인요청금액 12 Byte TEEN_UserID 틴캐시아이디 String 틴캐시사용자아이디 16 Byte Page 41
연동가이드작성자최재원검토자강석민 Page 42/55 TEEN_ApplNu m 틴캐시승인번호 String 틴캐시승인번호 8 Byte BCSH_ApplPric e BCSH_UserID BCSH_ApplNu m 도서상품권승인금액도서상품권사용자ID 도서상품권승인번호 String 도서상품권승인금액 12 Byte String booknlife 사용자아이디 20 Byte String 도서상품권승인번호 12 Byte [TABLE 2-11] 승인결과데이터 ( 전화결제 ) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) PHNB_Num 승인전화번호 String 전화번호 12 Byte [TABLE 2-12] 승인결과데이터 ( 전자지갑 [ 뱅크월렛 ]) 필드명한글명칭 Data Type 설명 크기 ( 최대 ) KWPY_CellPho ne KWPY_SalesA mount 휴대폰번호 String 스마트폰전화번호 ('-' 제외 ) 40Byte 거래금액 String 거래금액 Byte KWPY_Amount 공급가액 String 공급가액 ( 거래금액 -( 부가세 + 봉사료 )) 12Byte KWPY_Tax 부가세 String 부가세 12Byte KWPY_ServiceF ee 봉사료 String 봉사료 12Byte 가맹점설정에따라승인결과형식 (return content type) 을다양하게수신하실수있습니다. 승인결과형식은다음과같습니다. [TABLE 2-13] 리턴형식별승인결과예시 유형예 ContentType XML <?xml version="1.0" encoding="utf-8"?> <result> text/xml Page 42
연동가이드작성자최재원검토자강석민 Page 43/55 <appldate>20141211</appldate> <applnum>12858596</applnum> <applprice>50000</applprice> <appltime>135636</appltime> <buyeremail>test@kggroup.co.kr</buyeremail> <buyername> 홍길동 </buyername> <buyertel>010-1111-1111</buyertel> <cardbankcode>81</cardbankcode> <cardcode>17</cardcode> <cardnointerest>0</cardnointerest> <cardnum>532092000175</cardnum> <cardquota>0</cardquota> <clevent/> <currency>won</currency> <custemail>test@kggroup.co.kr</custemail> <expire/> <goodname>product</goodname> <gwcode>a</gwcode> <membernum/> <mid>inikpaytst</mid> <oid>inikpaytst_1418273735611</oid> <parentemail/> <paydevice>pc</paydevice> <paymethod>card</paymethod> <point>0</point> <price>50000</price> <prtccode>0</prtccode> <purchasecode/> <resultcode>0000</resultcode> <resultmsg> 정상처리되었습니다.</resultMsg> <terminalnum>0196282000</terminalnum> Page 43
연동가이드작성자최재원검토자강석민 Page 44/55 <tid>stdpaycardinikpaytst20141211135635953969</tid> </result> JSON { application/json "appldate": "20130219", "appltime": "165006", "paymethod": "VBank", "price": "1004", "resultcode": "0000", "resultmsg": " 정상처리되었습니다.", "tid": "StdpayVBNKINIpayTest20130219165005394245", } NVP appldate=20130219&appltime=164631&buyeremail=ehbang@inicis.com&buyername= 홍길동 &buyertel=01020001234¤cy=won&custemail=sample@inicis.com&goodname=p RODUCT&mid=INIpayTest&oid=INIpayTest_1361259979159&parentEmail=&payDevice=Mob ile&paymethod=vbank&price=1004&resultcode=0000&resultmsg= 정상처리되었습니다.&tid =StdpayVBNKINIpayTest20130219164630729304&vactBankCode=11&vactBankName= 농협중앙회 &vactdate=20130228&vactinputname= 홍길동 &vactname= 케이지이니시스 &vactnum= 01443364911441&vactTime=235900 text/plain Page 44
연동가이드작성자최재원검토자강석민 Page 45/55 3.5 Signature 생성 3.5.1 signature 개요 결제요청시등 HTTPS post 요청시가맹점의요청이정상적인요청인지여부 / 사용자의위변조방지를위해일부데이터를 SHA256 으로 Hash 한값 signature 는 form.submit 시적용됩니다. signature 생성은 Sample Source 를참고하여작성하시기바랍니다 3.5.2 signature 첨부대상 INIpay Standard 의모든요청 결제 ( 인증 ), 승인 APIsignature 생성대상필드 (Target) 모든요청의 signature 의생성방법동일하며, 요청별로생성대상필드가다름 * 요청별로명시된 signature 생성대상 (Target) 필드 를참조 인증요청 ( 결제요청 ) : oid, price, timestamp [TABLE 1-2] signature 생성대상 (Target) 필드 참조 승인요청 : authtoken, timestamp [TABLE 2-3] 승인요청 signature 생성대상 (Target) 필드 참조 3.5.3 signature 생성방법 위변조방지를위한보안조치로서필수체크데이터를 NVP 방식으로연결한데이터를 SHA256 으로 Hash 한값 * NVP : name and value parameters ex) name=value&name=value&name=value&name=value 필드순서유지 ( 알파벳순 ), 마지막 & 는생략, 공백생략, 모든대상필드는 Form 에설정되는데이터와동일한값을이용 Page 45
연동가이드작성자최재원검토자강석민 Page 46/55 3.5.4 signature 생성샘플 ( 결제요청 ) # 언어별제공된라이브러리소스를통해서생성가능합니다. signature 생성예 - Target 데이터 (signparam) oid=inipaytest_1361252896871&price=1004&×tamp=1361252896871 - Hash 데이터 ( 위 Target 데이터를 SHA256 Hash 한값 ) ec1e9c63ddad0b81f316ada2e3861e81db5f4f6652d9ff0f255b4cb5499ce893 잘못된 Target 데이터생성예 - 띄어쓰기및 & 중복의경우 원본 수정 oid=1231231&price=10000& ×tamp=1335247243103 oid=1231231&price=10000×tamp=1335247243103 - 마지막 & 가붙는경우 원본 수정 oid=1231231&price=10000×tamp=1335247243103& oid=1231231&price=10000×tamp=1335247243103 Page 46
연동가이드작성자최재원검토자강석민 Page 47/55 3.6 결제취소페이지작성 (INIStdCancel) 결제승인거래또는현금영수증발급요청거래에대한취소처리를수행합니다. TX 모듈을이용한취소를제공합니다. 이니시스 TX 모듈을설치해사용하는가맹점은추가로 설치할필요가없습니다. 3.7 승인취소요청페이지 (INIStdCancel.html) INIStdCancel.html mid hidden 필드정보를상점아이디로변경 / 설정합니다. 취소요청시입력되는정보는거래아이디 (tid), 상점아이디 (mid), 취소사유 (msg) 필드정보이며, tid 필드값은취소요청시마다바뀌며, mid 필드값은사용중인상점아이디값을설정합니다. msg 필드정보는차후취소원인을확인하기위한이력정보이므로, 입력하는것을권장합니다. 표 1 결제취소설정필드정보 필드명설명 Val Type Max Lan Tid [ 필수 ] 취소할거래의거래아이디 String 40 Mid [ 필수, hidden] 상점아이디. 실서비스시에는발급받은 아이디로변경. String 10 Msg [ 선택 ] 취소사유 String 100 cancelreason [ 선택 ] 1: 거래취소 / 2: 오류 / 3: 기타사항 * msg 를제외한모든필드들은필수입니다. 3.8 승인취소및결과확인페이지 제공된샘플소스 INIStdCance.xxxl 를참고바랍니니다. 키패스워드를잊었을경우는키파일재발급을요청합니다. 키패스워드는상점에서확인 / 관리되는 정보입니다. ( 이메일로전달받은키파일에포함된 readme.txt 파일에서도확인.) Page 47
연동가이드작성자최재원검토자강석민 Page 48/55 참고로, 키파일과키패스워드를모두확인할수없는상황에서는 [ 이니시스영업지원 ] 으로키파일 재발급요청을합니다. 거래아이디 (TID) 는 지불실패 시에도반환됩니다. 즉, 거래성공시에만반환되는것이아닙니다. Page 48
연동가이드작성자최재원검토자강석민 Page 49/55 4. 별첨 A.1. 결제수단코드 (gopaymethod) 지불수단이름신용카드실시간계좌이체 OKCashbag 포인트핸드폰무통장입금 ( 가상계좌 ) 폰빌, 전화결제문화상품권결제스마트문상결제틴캐시도서문화상품권해피머니상품권엘로페이케이페이페이핀간편결제전자지갑포인트상품권 키워드 Card DirectBank OCBPoint HPP VBank PhoneBill Culture DGCL TeenCash Bcsh HPMN YPAY Kpay Paypin EasyPay EWallet POINT GiftCard Page 49
연동가이드작성자최재원검토자강석민 Page 50/55 A.2. 결제수단코드 (paymethod) 지불수단이름신용카드 (ISP) 신용카드 ( 안심클릭 ) OK캐쉬백포인트 GS&POINT 삼성 U-point 실시간계좌이체 (K계좌이체) 실시간계좌이체 (I계좌이체) 휴대폰무통장입금 ( 가상계좌 ) 폰빌전화결제문화상품권틴캐쉬스마트문화상품권도서문화상품권해피머니상품권옐로페이뱅크월렛신용카드빌링키발급 키워드 VCard Card OCBPoint GSPT UPNT DirectBank idirectbank HPP VBank PhoneBill Culture TeenCash DGCL BCSH HPMN YPAY EWallet Auth A.3. 카드사승인코드 코드 카드사이름 코드 카드사이름 01 하나 ( 외한 ) 03 롯데 04 현대 06 국민 11 BC 12 삼성 14 신한 17 하나카드 Page 50
연동가이드작성자최재원검토자강석민 Page 51/55 코드 카드사이름 코드 카드사이름 16 NH 22 해외마스터 21 해외비자 24 해외아멕스 23 JCB 25 해외다이너스 A.4. 카드사코드 ( 결제창호출시제어코드 ) 코드 카드사이름 코드 카드사이름 01 하나 ( 외환 ) 03 롯데 04 현대 06 국민 11 BC 12 삼성 14 신한 21 해외 VISA 22 해외마스터 23 해외 JCB 26 중국은련 32 광주 33 전북 34 하나 35 산업카드 41 NH 43 씨티 44 우리 48 신협체크 51 수협 52 제주 54 MG새마을금고체크 71 우체국체크 95 저축은행체크 A.5. 카드발급사 ( 은행 ) 코드 코드 카드사이름 코드 카드사이름 02 한국산업은행 03 기업은행 04 국민은행 ( 주택은행 ) 05 하나은행 ( 구외환 ) 07 수협중앙회 11 농협중앙회 Page 51
연동가이드작성자최재원검토자강석민 Page 52/55 코드 카드사이름 코드 카드사이름 12 단위농협 16 축협중앙회 20 우리은행 21 신한은행 ( 조흥은행 ) 23 제일은행 25 하나은행 ( 서울은행 ) 26 신한은행 27 한국씨티은행 ( 한미은행 ) 31 대구은행 32 부산은행 34 광주은행 35 제주은행 37 전북은행 38 강원은행 39 경남은행 41 비씨카드 53 씨티은행 54 홍콩상하이은행 71 우체국 81 하나은행 83 평화은행 87 신세계 88 신한은행 ( 조흥통합 ) A.6. 은행 ( 증권사 ) 코드 코드 카드사이름 코드 카드사이름 02 한국산업은행 03 기업은행 04 국민은행 05 하나은행 ( 구외환 ) 06 국민은행 ( 구주택 ) 07 수협중앙회 11 농협중앙회 12 단위농협 16 축협중앙회 20 우리은행 21 구 ) 조흥은행 22 상업은행 23 SC제일은행 24 한일은행 25 서울은행 26 구 ) 신한은행 27 한국씨티은행 ( 구한미 ) 31 대구은행 32 부산은행 34 광주은행 35 제주은행 37 전북은행 Page 52
연동가이드작성자최재원검토자강석민 Page 53/55 코드 카드사이름 코드 카드사이름 38 강원은행 39 경남은행 41 비씨카드 45 새마을금고 48 신용협동조합중앙회 50 상호저축은행 53 한국씨티은행 54 홍콩상하이은행 55 도이치은행 56 ABN 암로 57 JP모건 59 미쓰비시도쿄은행 60 BOA(Bank of America) 64 산림조합 70 신안상호저축은행 71 우체국 81 하나은행 83 평화은행 87 신세계 88 신한 ( 통합 ) 은행 D1 유안타증권 ( 구동양증권 ) D2 현대증권 D3 미래에셋증권 D4 한국투자증권 D5 우리투자증권 D6 하이투자증권 D7 HMC 투자증권 D8 SK 증권 D9 대신증권 DA 하나대투증권 DB 굿모닝신한증권 DC 동부증권 DD 유진투자증권 DE 메리츠증권 DF 신영증권 DG 대우증권 DH 삼성증권 DI 교보증권 DJ 키움증권 DK 이트레이드 DL 솔로몬증권 DM 한화증권 DN NH증권 DO 부국증권 DP LIG 증권 A.7. 카드이벤트적용코드 코드 설명 1 당사 & 카드사부담일반무이자할부이벤트 12 카드사부담일반무이자 + 상점일반할인이벤트 Page 53
연동가이드작성자최재원검토자강석민 Page 54/55 코드 설명 14 카드사부담일반무이자 + 카드번호별할인이벤트 24 카드사부담일반무이자 + 카드 Prefix 별할인이벤트 A1 A2 A3 A4 A5 B4 B5 C0 C1 상점부담일반무이자할부이벤트상점일반할인이벤트상점무이자 + 상점일반할인이벤트상점무이자 + 카드번호별할인이벤트카드번호별할인이벤트상점무이자 + 카드 Prefix별할인이벤트카드 Prefix별할인이벤트당사 & 카드사부담특별무이자할부이벤트상점부담특별무이자할부이벤트 A.8. 인증결과코드 해당코드는참조용으로, 모든에러코드에대한명시되있지않으며, 언제든이변경될수있습니다. * 소스에코딩하지마시기바랍니다. 구분결과코드사유비고 인증성공 0000 성공정상적으로결제창을통해인증이완료된경우 ( 승인요청가능 ) V000 ~ V099 결제요청실패필수파라미터누락, 규칙에맞지않는파라미터, 주문번호중복등 V100 ~ V199 결제창표시실패표시가능결제수단없음등 인증실패 기타 V200 ~ V299 인증완료후실패인증완료후가맹점인증결과전송중실패등 V800 ~ V899 결제종료사용자취소, 결제요청시간초과, 위변조시등 R900 ~ V999 기타예상치못한실패등 A.9. 승인결과코드 해당코드는참조용으로, 모든에러코드에대한명시되있지않으며, 언제든이변경될수있습니다. * 소스에코딩하지마시기바랍니다. 구분결과코드사유비고 Page 54
연동가이드작성자최재원검토자강석민 Page 55/55 승인성공 0000 정상적으로승인이완료된경우 R100 ~ R199 승인요청실패필수파라미터누락, 규칙에맞지않는파라미터등 승인요청전 실패 R200 ~ R299 R300 ~ R399 승인처리불가실재승인요청등패승인처리중실패내부장애등 R900 ~ R999 기타예상치못한실패 Page 55