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


테스트 계정 다운로드
다운로드 버튼을 눌러
테스트 계정을 확인해 주세요.


INILite Key 세팅
가맹점 MID에 맞는 INILite Key 를 세팅해주세요.


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

실제 연동진행
가맹점 실서버 환경에 맞게
연동을 진행해주세요.
연동 준비하기
모바일결제 연동 전, 체크해야할 사항을 안내드립니다.
MID상점아이디
계약 완료 여부, 사용 가능 지불 수단 등은 계약담당자 문의INILite Key대칭키
가맹점관리자 ▶ 상점정보 ▶ 계약정보 ▶ KEY 정보 ▶ INILite/Express Key 생성 갱신 조회방화벽정보
| 항목 | 운영환경 |
|---|---|
| URL | inilitepay.inicis.com |
| IP | 183.109.71.67 118.129.210.29 |
| PORT | 443 |
| 연결방향 | OUTBOUND |
STEP 1빌키발급 요청
빌키발급 요청정보
- 빌키발급 URL : https://inilitepay.inicis.com/pay/card/billing
- HTTP Method : POST
- Content-type : application/x-www-form-urlencoded
- Accept-charset : UTF-8
| mid* | 가맹점 아이디 |
10 byte
|
|
|---|---|---|---|
| buyerTel* | 구매자 전화번호 |
40 byte
|
|
| buyerEmail* | 구매자 이메일주소 |
60 byte
|
|
| buyerName* | 구매자명 |
30 byte
|
|
| goodName* | 상품명 |
40 byte
|
|
| orderId* | 주문번호 반드시 Unique 값으로 생성 (거래추적 시 사용됨) |
64 byte
|
|
| price* | 금액 |
12 byte
|
|
| timestamp* | 전문생성시간 [YYYYMMDDhhmmss] |
14 byte
|
|
| returnUrl* | 가맹점 응답 URL |
1000 byte
|
|
| hashdata* | SHA512 Hash값 대상 : price + mid + orderId + timestamp + INILitekey |
HASH
N/A
|
|
| merchantRedirectData | 가맹점 전달 데이터 |
N/A
|
|
| customData | 커스텀 데이터 |
N/A
|
|
| customData 상세 | |||
| period | 제공기간 |
100 byte
|
|
STEP 2빌키발급 결과
※ 유의사항
해당 응답파라미터는 모든 프로세스 종료 후 최종적으로 전달되는 결과값 입니다.
- 응답파라미터는 추후 요건에 의해 추가될 수 있습니다.
- 실패 응답 시, 일부 파라미터 응답이 null 일 수 있습니다.
| resultCode | 결과코드 "SUCCESS":성공, 이외 실패 |
14 byte
|
|
|---|---|---|---|
| resultMessage | 결과메세지 |
N/A
|
|
| mid | 상점아이디 |
10 byte
|
|
| orderId | 주문번호 |
64 byte
|
|
| authkey | 빌키 발급 트랜잭션 ID |
40 byte
|
|
| tid | 거래번호 |
40 byte
|
|
| merchantRedirectData | 가맹점 전달 필드 |
N/A
|
|
| billkey | 발급된 빌링키 암호화 billkey 암호화 : AES256 암호화 후 UTF-8 URL Encode된 값, 복호화 하여 사용 필요 |
복호화샘플
40 byte
|
|
| billkeyDate | 빌키 발급 날짜 |
10 byte
|
|
| billkeyTime | 빌키 발급 시간 |
10 byte
|
|
| cardNumber | 카드번호 |
14 byte
|
|
| cardCode | 카드사 코드 |
10 byte
|
|
| cardCompanyName | 카드사명 |
14 byte
|
|
| cardType | 카드 타입 (0: 개인 / 1: 법인 ) |
10 byte
|
|
| cardTypeName | 카드 구분 명칭 (개인 / 법인) |
14 byte
|
|
| cardKind | 카드종류 (0: 신용카드 / 1: 체크카드 / 2: 기프트카드) |
10 byte
|
|
| cardKindName | 카드 종류 명칭 |
64 byte
|
|
| hashData | 빌키 hashData |
N/A
|
|
| kbpay | KB Pay 정보 (데이터 타입 : JSON Object) |
N/A
|
|
| kbpay 상세 | |||
| detailCardCode | 카드 상품코드 |
N/A
|
|
| detailCardName | 카드 상품명 |
N/A
|
|
| materialCode | 자채구분코드 |
N/A
|
|
| imagePath | 카드 이미지파일 URL |
N/A
|
|
| cardPostfix | 실카드 뒷 4자리 |
N/A
|
|
(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:// |
빌링승인
발급된 billkey 로 실과금요청을 위한 API 서비스 (PC/모바일 공통)
Quick Guide


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


billKey 세팅
발급받은 billKey 를 세팅해주세요.


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

실제 연동진행
가맹점 실서버 환경에 맞게
연동을 진행해주세요.
연동 준비하기
빌링승인 API 연동 전, 체크해야할 사항을 안내드립니다.
MID상점아이디
계약 완료 여부, 사용 가능 지불 수단 등은 계약담당자 문의INIAPI key대칭키
가맹점관리자 ▶ 상점정보 ▶ 계약정보 ▶ KEY 정보 ▶ INIAPI Key방화벽정보
| 항목 | 스테이징환경 | 운영환경 |
|---|---|---|
| URL | stginiapi.inicis.com | iniapi.inicis.com |
| IP | 118.129.210.153 | 118.129.210.166 183.109.71.79 |
| PORT | 443 | |
| 연결방향 | OUTBOUND | |
| 보안 프로토콜 | TLS 1.2 이상 지원 | |
STEP1빌링승인 요청
빌링승인 요청정보
- 요청전문 형식 : JSON (V2) NVP (V1)
- 빌링요청URL : https://iniapi.inicis.com/api/v1/billing
- Header 정보
POST /api/v1/billing HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
- 유의사항
-
각 파라미터는 key=value 로 세팅하여 POST 로 API 요청 ( JSON방식 요청불가 )
Form data 세팅 후 API 통신 구간에서 모든 value를 urlEncode 하여 전송 - 빌키발급결과 페이지 내 빌링승인 API 를 연동하실 경우, 결과페이지 새로고침 또는 재호출 시
빌링승인 API 가 중복으로 호출되어 중복결제되는 이슈가 발생될 수 있습니다.
반드시 빌링키발급과 빌링승인 API 를 분리하여 연동을 부탁드립니다.
| type* | 요청서비스 ["Billing" 고정] |
7 byte
|
|---|---|---|
| paymethod* | 지불수단 코드 [Card:신용카드, HPP:휴대폰] |
10 byte
|
| timestamp* | 전문생성시간 [YYYYMMDDhhmmss] |
14 byte
|
| clientIp* | 가맹점 요청 서버IP (추후 거래 확인 등에 사용됨) |
15 byte
|
| mid* | 상점아이디 |
10 byte
|
| url* | 가맹점 URL |
50 byte
|
| moid* | 주문번호 |
40 byte
|
| goodName* | 상품명 |
80 byte
|
| buyerName* | 구매자명 |
80 byte
|
| buyerEmail* | 구매자 이메일주소 "@", "." 외 특수문자 입력불가 |
60 byte
|
| buyerTel | 구매자 휴대폰번호 |
40 byte
|
| price* | 결제금액 |
10 byte
|
| billKey* | 승인요청할 빌링키 값 |
40 byte
|
| authentification* | 본인인증 여부 ["00" 고정] 본인인증 안함 가맹점으로 별도계약된 경우 "99" 로 세팅 |
2 byte
|
| regNo | 생년월일 [YYMMDD] 또는 사업자번호 |
ENC
10 byte
|
| cardPw | 카드비밀번호 앞 2자리 |
ENC
2 byte
|
| tax | 부가세 "부가세 업체정함" 계약가맹점만 설정필요 |
10 byte
|
| taxFree | 비과세 "부가세 업체정함" 계약가맹점만 설정필요 |
10 byte
|
| currency | 통화코드 [WON,USD] |
3 byte
|
| cardQuota | 할부기간 ["00":일시불, 그 외 : 02, 03 ...] |
2 byte
|
| quotaInterest | 무이자구분 ["1":무이자] "상점부담무이자" 계약 가맹점만 사용 |
1 byte
|
| hashData* | SHA512 HASH 한 값 대상 : INIAPIKey + type + paymethod + timestamp + clientIp + mid + moid + price + billKey |
HASH
128 byte
|
빌링승인 요청정보
- 요청전문 형식 : JSON (V2) NVP (V1)
- 빌링요청URL : https://iniapi.inicis.com/v2/pg/billing
- Header 정보
POST /v2/pg/billing HTTP/1.1
Host: iniapi.inicis.com
Content-type: application/json
- 유의사항
- 빌키발급결과 페이지 내 빌링승인 API 를 연동하실 경우, 결과페이지 새로고침 또는 재호출 시
빌링승인 API 가 중복으로 호출되어 중복결제되는 이슈가 발생될 수 있습니다.
반드시 빌링키발급과 빌링승인 API 를 분리하여 연동을 부탁드립니다.
| mid* | String | 상점아이디 |
10 byte
|
|---|---|---|---|
| type* | String | 요청서비스 ["billing" 고정] |
7 byte
|
| paymethod* | String | 지불수단 코드 [card:신용카드, HPP:휴대폰] |
10 byte
|
| timestamp* | String | 전문생성시간 [YYYYMMDDhhmmss] |
14 byte
|
| clientIp* | String | 가맹점 요청 서버IP (추후 거래 확인 등에 사용됨) |
15 byte
|
| hashData* | String | SHA512 HASH 한 값 대상 : INIAPIKey + mid + type + timestamp + data |
HASH
128 byte
|
| data* | Data | 요청데이터 |
N/A
|
| Data 상세 | |||
| url* | String | 가맹점 URL |
50 byte
|
| moid* | String | 주문번호 |
40 byte
|
| goodName* | String | 상품명 |
80 byte
|
| buyerName* | String | 구매자명 |
80 byte
|
| buyerEmail* | String | 구매자 이메일주소 "@", "." 외 특수문자 입력불가 |
60 byte
|
| buyerTel | String | 구매자 휴대폰번호 |
40 byte
|
| price* | String | 결제금액 |
10 byte
|
| billKey* | String | 승인요청할 빌링키 값 |
40 byte
|
| authentification* | String | 본인인증 여부 ["00" 고정] 본인인증 안함 가맹점으로 별도계약된 경우 "99" 로 세팅 |
2 byte
|
| regNo | String | 생년월일 [YYMMDD] 또는 사업자번호 |
ENC
10 byte
|
| cardPw | String | 카드비밀번호 앞 2자리 |
ENC
2 byte
|
| tax | String | 부가세 "부가세 업체정함" 계약가맹점만 설정필요 |
10 byte
|
| taxFree | String | 비과세 "부가세 업체정함" 계약가맹점만 설정필요 |
10 byte
|
| currency | String | 통화코드 [WON,USD] |
3 byte
|
| cardQuota | String | 할부기간 ["00":일시불, 그 외 : 02, 03 ...] |
2 byte
|
| quotaInterest | String | 무이자구분 ["1":무이자] "상점부담무이자" 계약 가맹점만 사용 |
1 byte
|
STEP2빌링승인 응답
※ 유의사항
해당 응답파라미터는 모든 프로세스 종료 후 최종적으로 전달되는 결과값 입니다.
- 응답파라미터는 추후 요건에 의해 추가될 수 있습니다.
- 실패 응답 시, 일부 파라미터 응답이 null 일 수 있습니다.
- 응답형식은 JSON 형식 입니다.
| resultCode | 결과코드 "00":성공, 이외 실패 |
6 byte
|
|---|---|---|
| resultMsg | 결과메세지 |
100 byte
|
| payDate | 거래일자 [YYYYMMDD] |
8 byte
|
| payTime | 거래시간 [hhmmss] |
6 byte
|
| payAuthCode | 승인번호 |
N/A
|
| tid | 거래번호 |
40 byte
|
| price | 거래금액 |
10 byte
|
| cardCode | 카드코드 |
2 byte
|
| cardQuota | 할부개월 ["00":일시불, "02":2개월, "03":3개월, ...] |
2 byte
|
| checkFlg | 카드구분 ["0":신용, "1":체크, "2":기프트] |
1 byte
|
| prtcCode | 부분환불 가능여부 ["1": 가능, "0": 불가능] |
1 byte
|
| usePoint | 포인트 금액 특정 가맹점 전용 응답 필드 |
12 byte
|
| cardPoint | 현대 mpoint 사용 거래(m) 특정 가맹점 전용 응답 필드 |
12 byte
|
| partnerDiscount | 제휴코드 특정 가맹점 전용 응답 필드 |
12 byte
|
| eventFlag | "0" 고정 특정 가맹점 전용 응답 필드 |
1 byte
|
| cardNumber | 카드번호 가맹점에서 설정한 카드정보 전송여부에 따라 응답 |
16 byte
|



