목차 KG 이니시스 Pub. Date: 2018. 10 Page I
목차 목차 1. 실시간빌링서비스개요...3 2. 실시간빌링서비스의조건...4 3. 메시지전달방식...5 3-1) 방화벽문제... 5 4. 처리절차...6 5. 빌링방법 - 실시간신용카드빌링...7 5.1 단계 - 실시간빌링을위한신용카드의유효성확인및등록단계... 7 5.2 단계 - 빌링요청단계... 10 6. 빌링방법 - 실시간휴대폰빌링... 14 6.1 단계 - 실시간빌링을위한휴대폰의유효성확인및등록단계... 14 6.2 단계 - 빌링요청단계... 17 7. 코드표... 20 7.1 카드사코드... 20 Page ii Pub. Date: 2018. 10
1. 실시간빌링서비스개요 상점고객이회원제서비스또는월정액과금상품구매요청단계에서, 이니시스가제공하는본인인증서비스수행후전달받은 KEY 를이용하여, 추후해당고객에대한과금필요시해당 KEY 를이니시스로전송하여실시간으로과금하는서비스. 이니시스는최초본인인증수행후, 고객의신용카드번호등의결제정보를대체하는빌키를상점에전달하며, 실시간빌링처리를위해상점에서빌키를전달하여야한다. ( 단, 자체가맹점의경우별도협의가필요할수있음 ) Pub. Date: 2018. 10 Page 3
2. 실시간빌링서비스의조건 1. 반드시실시간빌링서비스업체로당사에등록. 2. 현재실시간빌링가능카드.( 현재 2008 년 4 월 ) - 외한, 롯데, 삼성, 신한, 현대, 국민, 비씨, NH, 하나 SK, ( 씨티 ) - 당사는씨티카드와직접적인가맹점계약은되어있지않음. 3. 신용카드본인인증트랜잭션처리후전달받은 BillingKey 을실시간빌링요청시전송해야만빌링가능. Page 4 Pub. Date: 2018. 10
3. 메시지전달방식 이니시스가제공하는지불시스템을통해상점의지불서버와이니시스 PG 서버사이에 TCP/IP 소켓통신을통해메시지를송수신받아처리한다. 3-1) 방화벽문제 연결대상 : 203.238.37.3, 39.115.212.10 프로토콜 : TCP 포트번호 : 9400 연결방향 : OUTBOUND Pub. Date: 2018. 10 Page 5
4. 처리절차 1. 상점고객이본인인증트랜잭션을통해본인인증절차를거쳐 BillingKey 를받아상점 DB 에보관한다. (BillingKey : Billing 트랜잭션을위한기본 key ( 40 자리 )) 2. 빌링작업시빌링요청트랜잭션을통하여 BillingKey 를전송하여카드승인을받는다. Page 6 Pub. Date: 2018. 10
5. 빌링방법 - 실시간신용카드 빌링 5.1 단계 - 실시간빌링을위한신용카드의 유효성확인및등록단계 본인인증 API : AUTH 본인인증입력페이지 : INIauth_bill.html 본인인증처리, 결과페이지 : INIauth_bill.php 1. 본인인증입력페이지의입력파리미터정리.(INIauth_bill.html) Pub. Date: 2018. 10 Page 7
NAME VALUE NOTE MID BuyerName url price ini_offer_period goodname SessionKey Encrypted acceptmethod uid MerchantReserved3 20140101 부터 20140131 까지제공한다면 2014010120140131 BILLAUTH 해당값변경불가 ( 필수 ) 상점아이디 구매자명 상점 SITE URL 상품금액 제공기간 상품 플러그인에서자동입력 플러그인에서자동입력 개인 / 법인카드구분 ( 선택 ) - 개인 : PERCARD - 법인 : COCARD 플러그인에서자동입력 상점회원 ID( 추후문제발생시에검증용 ) 이외에 cardcode, version, clickcontrol, paymethod 가 hidden 타입으로있으면해당필드의값은플러그인에서자동으로처리하므로 value 에값을임으로채우지마시기바랍니다. 제공기간 (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"> 개인 / 법인카드구분 - acceptmethod value 에 BILLAUTH 값은필수 - 카드구분을원할시, BILLAUTH 값뒤에 : 을구분자로하여옵션셋팅개인 : PERCARD / 법인 : COCARD 옵션셋팅예 ) 개인카드시 Page 8 Pub. Date: 2018. 10
<input type= hidden name= acceptmethod value= BILLAUTH:PERCARD > 예 ) 법인카드시 <input type= hidden name= acceptmethod value= BILLAUTH:COCARD > 2. 본인인증처리, 결과페이지결과값정리.( INIauth_bill.php) A. 처리진행단계 i. 객체생성단계 $INIpay = new COM("INItx41.INItx41.1"); ii. iii. 인스턴스초기화 $PInst = $INIpay->Initialize(""); 거래유형설정 $INIpay->SetActionType($PInst, "AUTH_BILL"); iv. 정보설정 INIauth_bill.html 에서넘긴데이타를해당모듈에 Setting 하기위한단계 < 소스내용 > $INIpay->SetField ($PInst, "pgid", "IniTechPG_"); //PG ID ( 고정 ) $INIpay->SetField ($PInst, "spgip", "203.238.37.10"); // 예비 PG IP ( 고정 ) $INIpay->SetField ($PInst, "mid",$mid); // 상점아이디 $INIpay->SetField ($PInst, "admin", "1111");// 키패스워드 ( 상점아이디에따라변경 ) $inipay->m_currency = WON ; // 화폐단위 $inipay->m_price = $price; // 상품금액 $INIpay->SetField ($PInst, "buyername", $buyername); // 성명 $INIpay->SetField ($PInst, "encrypted", $encrypted); // 암호문 $INIpay->SetField ($PInst, "sessionkey", $sessionkey); // 암호문 $INIpay->SetField ($PInst, "uip", getenv("remote_addr")); //IP $INIpay->SetField ($PInst, "debug", "true"); // 로그모드 ("true" 로설정하면자세한로그가생성됨 ) $INIpay->SetField ($PInst, "merchantreserved3", " 예비 3"); // 예비 $INIpay->SetField ($PInst, "goodname", $goodname); // 상품명 $INIpay->SetField ($PInst, "url", "http://www.your_domain.co.kr"); // 홈페이지주소 (URL) v. 본인인증절차를통한실시간빌링등록요청 $INIpay->StartAction($PInst); vi. 결과받기 실시간빌링등록결과값받기. Pub. Date: 2018. 10 Page 9
vii. 인스턴스해제 표 1 결과값에대한정리 NAME VALUE NOTE ResultCode 00 또는 00 외의값 00 성공, 00 외의값은실패 ResultMsg CardCode Tid BillingKey 결제실패시에관련메시지 에러메시지 카드사코드 거래번호 40 자리 Billing 트랜잭션을위한기본 key ( 40 자리 ) 법인카드 / 개인카드여부 0 개인. 1- 법인. 카드사코드 01-외환카드 03-롯데카드 ( 구동양 ) 04-현대카드 ) 06-국민카드 11-BC 카드 12-삼성카드 13-LG 카드 14-신한카드 21-해외비자카드 22-해외마스타카드 23-해외 JCB 카드 24- 해외아멕스카드 25-해외다이너스카드 99-기타카드 5.2 단계 - 빌링요청단계 실시간빌링 API : ReqBill 실시간빌링입력페이지 : INIreqrealbill.html 실시간빌링처리, 결과페이지 : INIreqrealbill.php 1. 실시간빌링입력페이지의입력파리미터정리. Page 10 Pub. Date: 2018. 10
NAME VALUE NOTE MID BillingKey GoodName Price 상점아이디 Billing 트랜잭션을위한기본 key ( 40 자리 ) 상품명 가격 currency 원 : WON 통화 ( 원 : WON ) BuyerName buyeremail buyertel cardquota quotainterest 구매자명구매자이메일구매자핸드폰번호할부기간무이자유무 PayMethod Card 신용카드인경우 authentification 00 / 01 00 : 인증 ( 공인인증서로인증받지않은경우, 비밀번호 + 주민번호앞 6 자리필요 ) 01 : 세미인증 ( 공인인증으로인증받은빌키를이용하는경우, 비밀번호 + 주민번호앞 6 자리필요없음 ) 2. 실시간빌링처리, 결과페이지결과값정리. A. 처리진행단계 i. 객체생성단계 $INIpay = new COM("INItx41.INItx41.1"); ii. iii. 인스턴스초기화 $PInst = $INIpay->Initialize(""); 거래유형설정 $INIpay->SetActionType($PInst, "REQREALBILL"); iv. 정보설정 INIreqrealbill.html 에서넘긴데이타를해당모듈에 Setting 하기위한단계 < 소스내용 > $INIpay->SetField ($PInst, "pgid", "IniTechPG_"); //PG ID ( 고정 ) $INIpay->SetField ($PInst, "spgip", "203.238.37.10"); // 예비 PG IP ( 고정 ) Pub. Date: 2018. 10 Page 11
$INIpay->SetField ($PInst, "mid",$mid); // 상점아이디 $INIpay->SetField ($PInst, "admin", "1111");// 키패스워드 ( 상점아이디에따라변경 ) $INIpay->SetField ($PInst, "paymethod", "Card");// 지불방법 $INIpay->SetField ($PInst, "goodname", $goodname); // 상품명 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "currency", $currency); // 화폐단위 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "price", $price); // 가격 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "buyername", $buyername); // 성명 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "buyertel", $buyertel); // 이동전화 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "buyeremail", $buyeremail); // 이메일 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "cardquota", $cardquota); // 할부기간 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "quotainterest", $quotainterest); // 무이자할부여부 (1:YES, 0:NO) $INIpay->SetField ($PInst, "url", "http://www.your_domain.co.kr"); // 홈페이지주소 (URL) $INIpay->SetField ($PInst, "uip", getenv("remote_addr")); //IP $INIpay->SetField ($PInst, "debug", "true"); // 로그모드 ("true" 로설정하면자세한로그가생성됨 ) $INIpay->SetField ($PInst, "merchantreserved1", " 예비 1"); //Tax : 부가세,TaxFree : 면세 ( 예 : Tax=10&TaxFree=10) $INIpay->SetField ($PInst, "merchantreserved2", " 예비 2"); // 예비 2 $INIpay->SetField ($PInst, "merchantreserved3", " 예비 3"); // 예비 3 $INIpay->SetField ($PInst, "billkey", $billkey); //BillKey $INIpay->SetField ($PInst, "regnumber", $regnumber); // 주민번호앞 6 자리및사업자번호 10 자리 $INIpay->SetField ($PInst, "cardpass", $cardpass); // 카드비번. v. 빌링승인요청 $INIpay->StartAction($PInst); vi. 빌링승인결과 실시간빌링승인결과값받기. vii. 인스턴스해제 Page 12 Pub. Date: 2018. 10
표 2 결과값에대한정리 (INIreqrealbill.php) NAME VALUE NOTE ResultCode 00 또는 00 외의값 00 성공, 00 외의값은실패 ResultMsg AuthCode Tid PGAuthDate PGAuthTime 결제실패시에관련메시지 에러메시지신용카드승인번호거래번호 40 자리이니시스승인날짜이니시스승인시각 Pub. Date: 2018. 10 Page 13
6. 빌링방법 - 실시간휴대폰빌링 6.1 단계 - 실시간빌링을위한휴대폰의유효성 확인및등록단계 본인인증 API : AUTH 본인인증입력페이지 : INIauthbill_hpp.html 본인인증처리, 결과페이지 : INIauthbill_hpp.php NAME VALUE NOTE Mid buyername url goodname mid price sessionkey encrypted ini_offer_period 반드시결제금액으로입력해야함 옵션미사용시정기결제 상점아이디구매자명상점 SITE URL 상품상점아이디상품금액필수입력플러그인에서자동입력플러그인에서자동입력제공기간 acceptmethod BILLAUTH(HPP):HPP(4) 해당값을변경하시면안됨. 필수입력 uid Merchantreserved1 merchantreserved3 플러그인에서자동입력 상점주문번호설정시사용 상점회원 ID( 추후문제발생시에검증용 ) 이외에 cardcode, version, clickcontrol, paymethod 가 hidden 타입으로있으면해당필드의값은플러그인에서자동으로처리하므로 value 에값을임으로채우지마시기바랍니다. Page 14 Pub. Date: 2018. 10
1. 본인인증입력페이지의입력파리미터정리.( INIauthbill_hpp.html ) 제공기간 (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 자리가입력되어있어야함 ) 예 ) BILLAUTH(HPP): HPREG 계약방법이명확하지않은경우이니시스영업으로문의하시기 바랍니다. 상점주문번호설정안내 - 상점에서빌키를생성요청시주문번호를설정할경우예 ) 상점주문번호 M1101 MerchantReserved1 필드에 moid=m1101 을설정한다. 2. 본인인증처리, 결과페이지결과값정리.( INIauthbill_hpp.php) A. 처리진행단계 i. 객체생성단계 $INIpay = new COM("INItx41.INItx41.1"); ii. iii. 인스턴스초기화 $PInst = $INIpay->Initialize(""); 거래유형설정 $INIpay->SetActionType($PInst, "AUTH_BILL"); Pub. Date: 2018. 10 Page 15
iv. 정보설정 INIauth_bill.html 에서넘긴데이타를해당모듈에 Setting 하기위한단계 < 소스내용 > $INIpay->SetField ($PInst, "pgid", "IniTechPG_"); //PG ID ( 고정 ) $INIpay->SetField ($PInst, "spgip", "203.238.37.10"); // 예비 PG IP ( 고정 ) $INIpay->SetField ($PInst, "mid",$mid); // 상점아이디 $INIpay->SetField ($PInst, "admin", "1111");// 키패스워드 ( 상점아이디에따라변경 ) $INIpay->SetField ($PInst, "buyername", $buyername); // 성명 $INIpay->SetField ($PInst, "encrypted", $encrypted); // 암호문 $INIpay->SetField ($PInst, "sessionkey", $sessionkey); // 암호문 $INIpay->SetField ($PInst, "uip", getenv("remote_addr")); //IP $INIpay->SetField ($PInst, "debug", "true"); // 로그모드 ("true" 로설정하면자세한로그가생성됨 ) $INIpay->SetField ($PInst, "merchantreserved3", " 예비 3"); // 예비 $INIpay->SetField ($PInst, "goodname", $goodname); // 상품명 $INIpay->SetField ($PInst, "url", "http://www.your_domain.co.kr"); // 홈페이지주소 (URL) v. 본인인증절차를통한실시간빌링등록요청 $INIpay->StartAction($PInst); vi. 결과받기 실시간빌링등록결과값받기. vii. 인스턴스해제 Page 16 Pub. Date: 2018. 10
표 3 결과값에대한정리 NAME VALUE NOTE ResultCode 00 또는 00 외의값 00 성공, 00 외의값은 실패 ResultMsg 결제실패시에관련메시지 에러메시지 Tid 거래번호거래번호 40 자리 BillKey Billing 트랜잭션을위한기본 key ( 40 자리 ) nohpp 휴대폰번호 hcorp *** 이통사정보 6.2 단계 - 빌링요청단계 실시간빌링 API : ReqBill 실시간빌링입력페이지 : INIreq_hpp.html 실시간빌링처리, 결과페이지 : INIreq_hpp.php 1. 실시간빌링입력페이지의입력파리미터정리.(INIreq_hpp.html) NAME VALUE NOTE mid billkey goodname price buyername buyeremail buyertel regnumber 상점아이디 Billing 트랜잭션을위한기본 key ( 40 자리 ) 상품명 가격 구매자명 구매자이메일 구매자핸드폰번호 주민번호앞 7 자리 이외에 clickcontrol 은 hidden 타입으로있으면해당필드의값은플러그인에서자동으로처리하므로 value 에값을임으로채우지마시기바랍니다. 2. 실시간빌링처리, 결과페이지결과값정리.(INIreq_hpp.php) Pub. Date: 2018. 10 Page 17
A. 처리진행단계 i. 객체생성단계 $INIpay = new COM("INItx41.INItx41.1"); ii. iii. 인스턴스초기화 $PInst = $INIpay->Initialize(""); 거래유형설정 $INIpay->SetActionType($PInst, "REQREALBILL"); iv. 정보설정 INIreq_hpp.html 에서넘긴데이타를해당모듈에 Setting 하기위한단계 < 소스내용 > $INIpay->SetField ($PInst, "pgid", "IniTechPG_"); //PG ID ( 고정 ) $INIpay->SetField ($PInst, "spgip", "203.238.37.10"); // 예비 PG IP ( 고정 ) $INIpay->SetField ($PInst, "mid",$mid); // 상점아이디 $INIpay->SetField ($PInst, "admin", "1111");// 키패스워드 ( 상점아이디에따라변경 ) $INIpay->SetField ($PInst, "paymethod", "HPP");// 지불방법 $INIpay->SetField ($PInst, "goodname", $goodname); // 상품명 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "price", $price); // 가격 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "buyername", $buyername); // 성명 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "buyertel", $buyertel); // 이동전화 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "buyeremail", $buyeremail); // 이메일 ( 변경시에만설정 ) $INIpay->SetField ($PInst, "url", "http://www.your_domain.co.kr"); // 홈페이지주소 (URL) $INIpay->SetField ($PInst, "uip", getenv("remote_addr")); //IP $INIpay->SetField ($PInst, "debug", "true"); // 로그모드 ("true" 로설정하면자세한로그가생성됨 ) $INIpay->SetField ($PInst, "billkey", $billkey); //BillKey $INIpay->SetField ($PInst, "regnumber", $regnumber); // 주민번호앞 7 자리및사업자번호 10 자리. v. 빌링승인요청 $INIpay->StartAction($PInst); vi. 빌링승인결과 실시간빌링승인결과값받기. vii. 인스턴스해제 Page 18 Pub. Date: 2018. 10
표 4 결과값에대한정리 (INIreq_hpp.php) NAME VALUE NOTE ResultCode 00 또는 00 외의값 00 성공, 00 외의값은실패 ResultMsg Tid PGAuthDate PGAuthTime 결제실패시에관련메시지 에러메시지거래번호 40 자리이니시스승인날짜이니시스승인시각 Pub. Date: 2018. 10 Page 19
7. 코드표 7.1 카드사코드 코드 카드사이름 코드 카드사이름 01 외환 03 롯데 04 현대 06 국민 11 BC 12 삼성 13 LG 14 신한 15 한미 16 NH 17 하나 SK 21 해외비자 22 해외마스터 23 JCB 24 해외아멕스 25 해외다이너스 56 카카오뱅크 Page 20 Pub. Date: 2018. 10