KG 이니시스
Copyright 2008 INICIS Co, Ltd. All rights reserved. 본문서와정보는 ( 주 ) 이니시스의재산입니다. 또한, 모든정보는 ( 주 ) 이니시스소유정보이며,( 주 ) 이니시스의사전동의없이본문서의어떤정보도열람, 복사, 유용, 배포또는타인과공유되어서는안됩니다. 본문서의정보는변경될수있으며변경시, 본문서는수정될것입니다. 본문서의내용에관한어떠한의견이라도귀하의프로젝트또는사업담당자에게전달하여주십시오. Title: INIbill_windows.doc Author: 플랫폼개발팀 Version: 0.1.2 작성일 수정내용 작성자 문서버전 2008-02-28 최초작성 백승길 V 0.0.1 2010-02-08 문서포맷변경 최웅식 V 0.0.2 2010-11-10 하나 SK 카드사코드추가 최웅식 V 0.0.3 2013-03-12 빌링가능카드변경 장현찬 V 0.0.4 2016-04-12 실시간신용카드빌링옵션추가 - acceptmethod : BILLAUTH 오수민 V 0.0.5 2016-08-23 CI 및사명변경, 빌링본인인증값수정 장현찬 V 0.0.6 2016-09-08 빌링휴대폰제휴사변경관련하여옵션수정 이윤선 V 0.0.7 2016-10-27 아웃바운드 IP 추가 최정 V 0.0.8 2016-12-29 부가세 / 면세필드추가 정현성 v 0.0.9 2017-01-04 이통사정보필드응답값변경 김재호 v 0.1.0 2017-08-25 카카오뱅크카드사코드 유경선 v 0.1.1 2018-10-30 목동센터폐쇄에따른아웃바운드 IP 삭제 정현성 v 0.1.2 Page ii Pub. Date: 2018. 10
목차 목차 1. 실시간빌링서비스개요... 4 2. 실시간빌링서비스의조건... 5 3. 메시지전달방식... 6 3.1 방화벽문제... 6 4. 처리절차... 7 5. 빌링방법 - 실시간빌링... 8 5.1 신용카드빌링... 8 5.1.1 실시간빌링을위한신용카드의유효성확인및등록단계... 8 5.1.2 빌링요청단계... 11 5.2 핸드폰빌링... 13 5.2.1 실시간휴대폰빌링을위한휴대폰의유효성확인및등록단계... 13 5.2.2 빌링요청단계... 16 6. 코드표... 18 6.1 카드사코드... 18 Pub. Date: 2018. 10 Page III
1. 실시간빌링서비스개요 상점고객이회원제서비스또는월정액과금상품구매요청단계에서, 이니시스가제공하는본인인증서비스수행후전달받은 KEY 를이용하여, 추후해당고객에대한과금필요시해당 KEY 를이니시스로전송하여실시간으로과금하는서비스. Page 4 Pub. Date: 2018. 10
2. 실시간빌링서비스의조건 1. 반드시실시간빌링서비스업체로당사에등록. 2. 현재실시간빌링가능카드.( 현재 2013 년 3 월 ) - 외한, 롯데, 삼성, 신한, 현대, 국민, 비씨, NH, 하나 SK, ( 씨티 ) - 당사는씨티카드와직접적인가맹점계약은되어있지않음. 3. 신용카드본인인증트랜잭션처리후전달받은 BillingKey 을실시간빌링요청시전송해야만빌링가능. Pub. Date: 2018. 10 Page 5
3. 메시지전달방식 이니시스가제공하는지불시스템을통해상점의지불서버와이니시스 PG 간 TCP/IP 소켓통신을통해메시지를송수신받아처리한다. 3.1 방화벽문제 연결대상 : 203.238.37.3, 39.115.212.10 프로토콜 : TCP 포트번호 : 9400 연결방향 : OUTBOUND Page 6 Pub. Date: 2018. 10
4. 처리절차 1. 상점고객이본인인증트랜잭션을통해본인인증절차를거쳐 BillingKey 를받아 상점 DB 에보관한다. (BillingKey : Billing 트랜잭션을위한기본 key ( 40 자리 )) 2. 빌링작업시빌링요청트랜잭션을통하여 BillingKey 를전송하여승인을받는다. Pub. Date: 2018. 10 Page 7
5. 빌링방법 - 실시간빌링 5.1 신용카드빌링 5.1.1 실시간빌링을위한신용카드의유효성확인및등록단계 본인인증 API : AUTH 본인인증입력페이지 : INIauth_bill.html 본인인증처리, 결과페이지 : INIauth_bill.php 요청필드 예시 설명 필수여부 길이 (Max) mid INIBillTst 이니시스상점아이디 Yes Fixed admin 1111 상점키패스워드 Yes Fixed buyername 홍길동 구매자명 Yes 30 encrypted 암호화데이터 플러그인에서사용하는예약필드 Yes N/A sessionkey 암호화데이터 플러그인에서사용하는예약필드 Yes N/A goodname 축구공 상품명 No 80 url http://www.xx.kr 상점url ( 내부참고용 ) Yes 100 price 1000 상품금액 No Fixed ini_offer_period 20140101 부터 20140131 까지제공한다면 2014010120140131 제공기간 No N/A Page 8 Pub. Date: 2018. 10
merchantreserved3 예비필드 결과필드 예시 설명 길이 (Max) resultcode 00 : 성공 2 이외실패 Success message : resultmsg [ 신용카드 본인인증이성공하였습니다.] 200 결과메시지 Failure message : [1223][ 인증실패 유효기간오류 ] cardcode 02 카드코드 2 tid INIpayBillINIBillTst20091216110906437565 거래번호 40 billkey 39ded0b6306b96b8b3166d02de7ffdd8639c5b24 BILL KEY. 40 BILLAUTH 해당값변경불가 ( 필수 ) acceptmethod nohpp 개인 / 법인카드구분 ( 선택 ) - 개인 : PERCARD - 법인 : COCARD 01112458745 모바일인증요청일경우만반환 11 No N/A 제공기간 (ini_offer_period) 상세설정안내 - 일자기준으로제공기간표시예 ) 20140101 부터 20140131 까지제공한다면 <input type=hidden name=ini_offer_period value="2014010120140131"> - 일자 + 시간까지포함해서제공기간표시예 ) 20140101 10:00 부터 20140131 23:00 까지제공한다면 <input type=hidden name=ini_offer_period value="201401011000201401312300"> Pub. Date: 2018. 10 Page 9
개인 / 법인카드구분 - acceptmethod value 에 BILLAUTH 값은필수 - 카드구분을원할시, BILLAUTH 값뒤에 : 을구분자로하여옵션셋팅 개인 : PERCARD / 법인 : COCARD 옵션셋팅 예 ) 개인카드시 <input type= hidden name= acceptmethod value= BILLAUTH:PERCARD > 예 ) 법인카드시 <input type= hidden name= acceptmethod value= BILLAUTH:COCARD > Page 10 Pub. Date: 2018. 10
5.1.2 빌링요청단계 실시간빌링 API : ReqBill 실시간빌링입력페이지 : INIreqrealbill.html 실시간빌링처리, 결과페이지 : INIreqrealbill.asp 요청필드 예시 설명 필수여부 길이 (Max) mid INIBillTst 상점아이디 Yes Fixed admin 1111 상점개인키패스워드 Yes Fixed debug true/false true: 상세한로그를남김 Yes Fixed url http://www.xx.kr 상점url ( 내부참고용 ) Yes 100 paymethod Card or HPP 걸제수단 Yes Fixed buyername 홍길동 구매자명 NO 30 buyertel 0105584878 구매자연락처 NO 20 buyeremail abc@abc.com 구매자이메일 NO 60 goodname 축구공 상품명 NO 80 cardquota 00 할부개월 00: 일시불 02:2개월 yes Fixed... 12:12개월 price 1000 상품가격 yes Fixed currency WON / USD 화페단위 KR : WON yes Fixed US : USD oid 384d91ld94 상점주문번호 NO 40 quotainterest 0 / 1 무이자유무 Yes Fixed Pub. Date: 2018. 10 Page 11
0 : 일반할부 1 : 무이자할부 billkey Billing Key Yes Fixed merchantreserved1 예비필드1 Tax : 부가세 / TaxFree : 면세 ( 예 Tax=100&TaxFree=900) NO N/A merchantreserved2 예비필드2 NO N/A merchantreserved3 예비필드3 NO N/A authentification 00 / 01 00 : 인증 ( 공인인증서로인증받지않은경우, 비밀번호 + 주민번호앞 6자리필요 ) 01: 세미인증 ( 공인인증로인증받은빌키를이용하는경우, 비밀번호 + 주민번호앞 6자리필요없음.) Yes 2 regnumber 주민번호앞 6 자리및사업자번호입력 authentification 이 00 일경우 NO cardpass 02 키드비밀번호번 ( 앞 2 자리 ) authentification 이 00 일경우 NO resultcode resultmsg 결과필드예시설명 00 : 성공 01 : 실패 Success message : [ 신용카드 빌링이정상적으로이루어졌습니다.] Fail message : [1294][ 신용카드 기간만료카드 ] 결과코드 2 결과메시지 200 tid INIpayBillINIBillTst20091216142 119937565 거래번호 40 authcode 신용카드승인번호 8 pgauthdate 20091216 승인날짜 (yyyymmdd) 8 pgauthtime 210212 승인시간 (hhmmss) 6 cardnumber 49062540****2545 카드번호 16 길이 (Max) Page 12 Pub. Date: 2018. 10
5.2 핸드폰빌링 5.2.1 실시간휴대폰빌링을위한휴대폰의유효성확인및등록단계 본인인증 API : AUTH_BILL 본인인증입력페이지 : INIauthbill_hpp.html 본인인증처리, 결과페이지 : INIauthbill_hpp.asp 요청필드 예시 설명 필수여부 길이 (Max) mid INIBillTst 이니시스상점아이디 Yes Fixed admin 1111 상점키패스워드 Yes Fixed buyername 홍길동 구매자명 Yes 30 encrypted 암호화데이터 플러그인에서사용하는예약필드 Yes N/A sessionkey 암호화데이터 플러그인에서사용하는예약필드 Yes N/A goodname 축구공 상품명 No 80 url http://www.xx.kr 상점url ( 내부참고용 ) Yes 100 price 1000 상품금액 No Fixed ini_offer_period 옵션미사용시정기결제 제공기간 No N/A acceptmethod BILLAUTH(HPP):HPP(4) 소스내주석참조 Yes N/A INIregno 주민번호앞 7 자리 Merchantreserved1 상점주문번호설정 ( 옵션 ) merchantreserved3 예비필드 결과필드예시설명길이 (Max) 2 resultcode 00 : 성공 No N/A Pub. Date: 2018. 10 Page 13
이외실패 Success message : resultmsg [ 신용카드 본인인증이성공하였습니다.] 200 결과메시지 Failure message : [1223][ 인증실패 유효기간오류 ] cardcode 02 카드코드 2 tid INIpayBillINIBillTst20091216110906437565 거래번호 40 billkey 39ded0b6306b96b8b3166d02de7ffdd8639c5b24 BILL KEY. 40 nohpp 01112458745 모바일인증요청일경우만반환 11 hcorp 이통사정보 이외에 version, clickcontrol 해당필드의값은플러그인에서자동으로처리하므로 value 에값을임으로채우지마시기바랍니다. 제공기간 (ini_offer_period) 상세설정안내 - 월자동결제표시 M2, m2 예 ) <input type=hidden name=ini_offer_period value="m2" - 연자동결제표시 Y2, y2 예 ) <input type=hidden name=ini_offer_period value="y2"> - 24 시간표시 T2, t2 예 ) <input type=hidden name=ini_offer_period value="t2"> acceptmethod 상세설정안내 - 이니시스와계약한빌링방법이컨텐츠인경우예 ) BILLAUTH(HPP):HPP(4) - 이니시스와계약한빌링방법이실물인경우예 ) BILLAUTH(HPP):HPP(5) - 주민번호앞 7 자리플러그인자동입력옵션 ( 바로아래 INIregno 필드에주민번호앞 7 자리가입력되어있어야함 ) Page 14 Pub. Date: 2018. 10
예 ) BILLAUTH(HPP): HPREG 계약방법이명확하지않은경우이니시스영업으로문의하시기바랍니다. 상점주문번호설정안내 - 상점에서빌키를생성요청시주문번호를설정할경우예 ) 상점주문번호 M1101 merchantreserved1 필드에 moid=m1101 을설정한다. Pub. Date: 2018. 10 Page 15
5.2.2 빌링요청단계 실시간빌링 API : REQREALBILL 실시간빌링입력페이지 : INIreq_hpp.html 실시간빌링처리, 결과페이지 : INIreq_hpp.asp 요청필드 예시 설명 필수여부 길이 (Max) mid INIBillTst 상점아이디 Yes Fixed admin 1111 상점개인키패스워드 Yes Fixed debug true/false true: 상세한로그를남김 Yes Fixed url http://www.xx.kr 상점url ( 내부참고용 ) Yes 100 paymethod Card or HPP 걸제수단 Yes Fixed buyername 홍길동 구매자명 NO 30 buyertel 0105584878 구매자연락처 NO 20 buyeremail abc@abc.com 구매자이메일 NO 60 goodname 축구공 상품명 NO 80 price 1000 상품가격 yes Fixed currency WON / USD 화페단위 KR : WON yes Fixed US : USD oid 384d91ld94 상점주문번호 NO 40 billkey Billing Key Yes Fixed merchantreserved1 예비필드1 NO N/A merchantreserved2 예비필드2 NO N/A merchantreserved3 예비필드3 NO N/A Page 16 Pub. Date: 2018. 10
regnumber resultcode resultmsg 휴대폰의유효성확인및등록단계에서플러그인창에서입력했던고객주민번호앞 7 자리 ( 법인휴대폰사용불가 ) 결과필드예시설명 00 : 성공 01 : 실패 Success message : [ 신용카드 빌링이정상적으로이루어졌습니다.] Fail message : [1294][ 신용카드 기간만료카드 ] 결과코드 2 결과메시지 200 tid INIpayBillINIBillTst20091216142 119937565 거래번호 40 pgauthdate 20091216 승인날짜 (yyyymmdd) 8 pgauthtime 210212 승인시간 (hhmmss) 6 NO 길이 (Max) Pub. Date: 2018. 10 Page 17
6. 코드표 6.1 카드사코드 코드 카드사이름 코드 카드사이름 01 외환 03 롯데 04 현대 06 국민 11 BC 12 삼성 13 LG 14 신한 15 한미 16 NH 17 하나 SK 21 해외비자 22 해외마스터 23 JCB 24 해외아멕스 25 해외다이너스 56 카카오뱅크 Page 18 Pub. Date: 2018. 10