모바일 빌링키발급
KG이니시스 결제창을 호출하여 정기결제를 위한 billkey 발급 서비스
Quick Guide


샘플 다운로드
개발 언어에 맞는 샘플을
다운로드 받아 주세요.


리턴 URL 수정
결과값을 수신받을 수 있는
리턴 URL 을 설정해주세요.


테스트 실행 및 결과확인
결제 진행과정과
응답결과를 확인해 주세요.

실제 연동진행
가맹점 실서버 환경에 맞게
연동을 진행해주세요.
연동 준비하기
모바일결제 연동 전, 체크해야할 사항을 안내드립니다.
MID상점아이디
계약 완료 여부, 사용 가능 지불 수단 등은 계약담당자 문의INILite key대칭키
가맹점관리자 ▶ 상점정보 ▶ 계약정보 ▶ KEY 정보 ▶ INILite/Express Key 생성 갱신 조회방화벽정보
| 항목 | 운영환경 | |
|---|---|---|
| URL | inilite.inicis.com | |
| IP | 203.238.37.166 183.109.71.80 |
|
| PORT | 443 | |
| 연결방향 | OUTBOUND | |
| 프로토콜 | TLS 1.2 이상 지원 | |
STEP 1빌키발급 요청
빌키발급 요청정보
- 신용카드 빌키발급 URL : https://inilite.inicis.com/inibill/inibill_card.jsp
- 휴대폰 빌키발급 URL : https://inilite.inicis.com/inibill/inibill_hpp.jsp
- HTTP Method : POST
- Accept-charset : UTF-8
- 공통
- 신용카드
- 휴대폰
| mid* | 상점아이디 |
10 byte
|
|---|---|---|
| authtype* | 인증구분 ["D" 고정] |
1 byte
|
| orderid* | 주문번호 반드시 Unique 값으로 생성 (거래추적 시 사용됨) |
64 byte
|
| price* | 결제금액 |
12 byte
|
| timestamp* | 전문생성시간 [YYYYMMDDhhmmss] |
14 byte
|
| returnurl* | 결과수신 URL |
N/A
|
| period* | 제공기간 ["Y2":연 자동결제, "M2":월 자동결제, "YYYYMMDDYYYYMMDD":시작일종료일] |
24 byte
|
| goodname* | 상품명 |
40 byte
|
| buyername* | 구매자명 |
30 byte
|
| buyertel | 구매자 휴대폰번호 |
20 byte
|
| buyeremail | 구매자 이메일주소 |
60 byte
|
| merchantreserved | 상점 예약필드 |
1000 byte
|
| hashdata* | SHA256 Hash값 대상 : mid + orderid + timestamp + INILitekey |
HASH
64 byte
|
| carduse | 개인/법인카드 사용선택 ["percard":개인카드만,"cocard":법인카드만] |
7 byte
|
|---|---|---|
| period_custom | 별도 제공기간 (미세팅 시 period 값 표시) |
24 byte
|
| type* | 휴대폰결제 상품유형 [1:컨텐츠, 2:실물] 계약사항에 맞게 세팅필요 |
유의사항
1 byte
|
|---|
STEP 2빌키발급 결과
※ 유의사항
해당 응답파라미터는 모든 프로세스 종료 후 최종적으로 전달되는 결과값 입니다.
- 응답파라미터는 추후 요건에 의해 추가될 수 있습니다.
- 실패 응답 시, 일부 파라미터 응답이 null 일 수 있습니다.
- 공통
- 신용카드
- 휴대폰
| resultcode | 결과코드 "00":성공, 이외 실패 |
4 byte
|
|---|---|---|
| resultmsg | 결과메세지 |
N/A
|
| pgauthdate | 거래일자 [YYYYMMDD] |
8 byte
|
| pgauthtime | 거래시간 [hhmmss] |
6 byte
|
| tid | 거래번호 |
40 byte
|
| mid | 상점아이디 |
10 byte
|
| orderid | 주문번호 (빌키발급 요청 시 세팅한 값) |
N/A
|
| billkey | 발급된 빌링키 |
40 byte
|
| authkey | 빌링인증 트렌젝션 ID |
40 byte
|
| merchantreserved | 상점 예약필드 |
1000 byte
|
| cardcd | 카드코드 |
2 byte
|
|---|---|---|
| cardno | 카드번호 |
16 byte
|
| cardkind | 카드구분 [0: 개인카드, 1:법인카드] |
1 byte
|
| CheckFlag | 카드종류 [0: 신용카드, 1: 체크카드, 2: 기프트카드] |
1 byte
|
| data1 | 카드비밀번호 앞2자리 (AES256 암호화 후 UTF-8 URL Encode된 값) 특정가맹점만 사용 |
복호화샘플
28 byte
|
| hppcorp | 휴대폰통신사 [*** 고정] |
3 byte
|
|---|
(추가) 보안강화
보안강화 방법 (선택사항)
모바일 빌링키발급 시 보안강화 옵션에 대해 안내드립니다.
- 요청전문 내 hashdata 생성 시 hash 대상파라미터 내 price 값이 추가됩니다.
- billkey 응답 시 암호화된 값으로 응답됩니다.
- 보안강화 요청
- 보안강화 응답
| flg_crypto | 보안추가 사용여부 ["Y": 사용] |
1 byte
|
|---|---|---|
| hashdata | 전문위변조 HASH 항목추가 hash(price+mid+orderid+timestamp+INILitekey) |
N/A
|
| billKey | 발급된 빌링키 암호화 billkey 암호화 : AES256 암호화 후 UTF-8 URL Encode된 값 |
복호화샘플
40 byte
|
|---|
(WebView) 앱 연동 참고사항
어플리케이션 내 WebView 에서 INIpayMobile 을 구현하는 경우에 해당합니다.
WebView 에서 INIpayMobile 을 띄우는 방식은 기본 모바일 웹 연동방법과 동일합니다.
이에, 해당 가이드는 3rd-party 앱 호출 시 주의사항 및 '결제 앱 미 설치 시, 앱 스토어 이동 이슈' 등의 내용을 주로 다룹니다.
안드로이드
A. WebViewClient 를 상속 받은 Class 를 구현하시고, shouldOverrideUrlLoading 을 호출해주세요.
B. shouldOverrideUrlLoading 함수 내에, 감지되는 URL 별로 분기처리를 해주세요.
C. 예외처리를 통해 startActivity 에 따른 앱 호출 및 마켓으로 이동할 수 있도록 구현해주세요.
@SuppressWarnings("deprecation") @Override public boolean shouldOverrideUrlLoading(WebView view, String url) { if( !url.startsWith("http://") && !url.startsWith("https://") ) { Intent intent; try { intent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME); Uri uri = Uri.parse(intent.getDataString()); startActivity(new Intent(Intent.ACTION_VIEW, uri)); return true; } catch (URISyntaxException ex) { return false; } catch (ActivityNotFoundException e) { try { Intent marketIntent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME); String packageNm = marketIntent.getPackage(); marketIntent = new Intent(Intent.ACTION_VIEW); marketIntent.setData(Uri.parse("market://details?id=" + packageNm)); startActivity(marketIntent); return true; } catch (URISyntaxException e1) { return false; } } } else { view.loadUrl(url); return false; } }
✔️ Android API 21 이상 체크사항
Android API 21 부터는 webview에서 Insecurity Page에 대한 Access 및 Mixed contents, Third party cookies 사용을 차단합니다.
Insecurity Page 에 대한 Access 차단으로 returnUrl 의 scheme가 http 인 경우, 빌키 발급 결과가 전달되지 않을 수 있으니 하기 설정 확인바랍니다.
또한, Third party cookies 사용의 차단으로 안심클릭 카드 결제 진행 시, 보안 키보드를 불러오지 못하는 이슈 등이 발생할 수 있습니다.
if (Build.VERSION.SDK_INT > 21) { // Insecurity Page 에 대한 Access 허용 설정 sampleWebView.getSettings().setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW); // setAcceptThirdPartyCookies : true 설정 CookieManager cookieManager = CookieManager.getInstance(); cookieManager.setAcceptCookie(true); cookieManager.setAcceptThirdPartyCookies(sampleWebView, true); }
✔️ Android API 30 이상 체크사항
Android11 이전 버전 OS 에서는 PackageManager 에서 제공하는 메소드(queryIntentActivities(), getInstalledApplications(), resolveActivity() ) 등 을 사용하여 앱 설치 유무를 확인하였습니다.
Android11(API 30) 부터는 패키지 가시성 제한 으로 INIpayMobile 결제창에서 사용하는 외부 앱 호출 시 패키지 정보로 앱 설치 여부를 확인하고 있는 경우, 정상 설치가 되어 있어도 마켓으로 이동하는 문제가 발생할 수 있습니다
이에, 두가지 방안 중 선택하여 연동해주시면 됩니다.
방안 1 요소에 패키지 정의
- AndroidManifest.xml 파일 수정
- AndroidManifest.xml 파일 요소에 패키지를 정의하면 패키지의 가시성이 확보됩니다.
- 장점 : 코드 수정 없이 AndroidManifest 파일만 수정
- 단점 : 패키지 목록 관리 필요 ( 신규 결제 앱 출시에 따라 패키지 추가 등록 필요)
방안 2 shouldOverrideUrlLoading() 예외처리 로직 추가
- startActivity() 호출 시, ActivityNotFoundException 예외 발생한 경우, 앱이 설치되지 않은 것으로 간주하고 앱 설치를 위해 마켓으로 이동 처리
- 장점 : 패키지 목록 관리가 필요하지 않음
- 단점 : 민감한 Webview 처리 로직 수정 필요
✔️ 주의사항
주의사항 1 USER AGENT 수정 issue
신용카드 결제 시 각 카드사 ACS 페이지에서는 사용자의 USER AGENT 를 검증하고 있습니다. (검증방식은 카드사별 상이) 가맹점 앱에서 USER AGENT 를 임의로 변경하는 경우, 카드사 인증실패가 발생할 수 있으니 이점 유의 바랍니다
✔️ 안드로이드 PackageName
| 카드사 | 패키지명 | |
|---|---|---|
| 카카오 | com.kakao.talk | |
IOS
A. Info.plist 에 타 앱 호출을 위한 카드사 App Scheme을 등록해주세요.
B. 웹페이지 로딩이 호출 될때 요청, 탐색 등을 위한 WKNavigationDelegate 메서드를 구현해주세요.
C. canOpenURL 여부에 따라, 앱 호출 및 마켓으로 이동 할 수 있도록 구현해주세요.
func webView( _ webView: WKWebView,decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { if let scheme = navigationAction.request.url?.scheme, scheme != "http" && scheme != "https" { if let openApp = navigationAction.request.url, UIApplication.shared.canOpenURL(openApp) { // ios version 별 처리 if #available(iOS 10.0, *) { UIApplication.shared.open(openApp, options: [:], completionHandler: nil) } else { UIApplication.shared.openURL(openApp) } } else { // 타 앱(결제앱) 호출 불가 및 미설치에 대한 처리 // let alert = UIAlertController(title: "알림", message: "앱 미설치", preferredStyle: .actionSheet) } decisionHandler(WKNavigationActionPolicy.cancel) } else { decisionHandler(WKNavigationActionPolicy.allow) } }
✔️ IOS 9 이상 체크사항
IOS9 업데이트 이후, APP 내 보안정책 강화로 canOpenUrl 또는 openUrl 함수 사용 시, info.plist 파일에 LSApplicationQueriesSchemes 배열을 정의하여 호출할 App scheme list 를 등록 해주셔야 합니다.
info.plist<key>LSApplicationQueriesSchemes</key> <array> <string>kb-screen</string> <string>kakaotalk</string> ...... </array>
✔️ IOS App Scheme
| 신용카드 | App Scheme |
|---|---|
| 국민 (KBPay) | kb-screen:// |
| 카카오 | kakaotalk:// |




