공통가이드

개발 전 확인이 필요한 공통적인 가이드

환경정보

프로토콜

고객사 API는 SChannel용 프로토콜로서 TLS(전송 계층 보안) 1.2 이상을 지원합니다.

테스트 고객사

테스트용 정보로 PG API 연동 테스트가 가능합니다.

테스트 고객사
파라미터 파라미터 값
고객사 아이디 o2o
API Key - search 키 값 생성 필요
API Key - payment 키 값 생성 필요

통신규칙

표준 RESTful-API 통신 방식을 따르며, HTTP 1.1 Specification을 준수합니다.
HTTP Method, Resource URL을 요청하면, JSON 데이터를 응답합니다.

응답 데이터 유형

JSON format

{
    “date”: “응답 데이터",
    “ret_code”: 응답 코드,
    “ret_msg”: “응답 메시지"
}
                                

성공 응답 유무

Http Status Code 200 응답은 성공, 그 외 모든 값(200이 아닌 값)은 실패를 의미합니다. 요청 처리 실패 시 반환되는 error 오브젝트 메시지를 반드시 확인해야 합니다. 고객사의 fall_url 이동 시, 요청 처리 실패에 대한 ret_code, ret_msg 정보가 POST 데이터로 반환됩니다.

성공: HTTP Status Code = 200, data 오브젝트 반환

200: OK
{
    “date”: “응답 데이터",
    “ret_code”: 응답 코드,
    “ret_msg”: “응답 메시지"
}
                                

실패: HTTP Status Code <> 200, error 오브젝트 반환

400: Bad Request
{
    “ret_code”: 응답 코드,
    “ret_msg”: “응답 메시지"
}
                                

보안

API 인증

고객사 계약 후 발급되는 API 키(key)를 Http Request Header Authorization 항목으로 보내주시기 바랍니다. 고객사 API 키는 결제(payment), 조회(search)용 두 가지가 발급되므로 용도에 맞게 사용하고, 웹사이트에 노출(외부 유출)되지 않도록 주의가 필요합니다. API 키는 고객사 관리자 웹사이트에서 확인하실 수 있습니다.

Authorization: SPGKEY (API Key)
                                

결제 인증 ∙ 승인 토큰

고객사 API에서 응답하는 인증 토큰(결제요청 API의 redirect_url 중 token 파라미터)으로 PG 웹 화면 요청의 유효성을, 승인 토큰(사용자 결제가 완료되면, 고객사 return_url로 전달)으로 고객 사 결제 승인 요청의 유효성을 확인합니다. 인증 토큰의 만료 시간은 30분, 승인 토큰의 만료 시간은 1분 입니다.

결제수단 & 오류코드

결제수단

결제수단
결제수단 코드 결제수단 코드 설명
selpay 통합결제창(간편결제, 신용카드, 신용카드(카드번호입력), 가상계좌 선택 UI 호출)
bizselpay 법인통합결제창(신용카드(카드번호입력), 가상계좌, 연계대출 선택 UI 호출)
card 일반 신용/체크카드
nauthcard 비인증 신용/체크카드 (개인/법인)
va 가상계좌
shpaycard 전용페이 신용/체크카드
shpaybank 전용페이 계좌이체
shpay 전용페이 (결제수단 선택 UI 호출)
zeropay 제로페이
seoulpay 서울페이
konai 지역화폐 - 코나아이
komsco 지역화폐 - 조폐공사
nicepay 지역화폐 - 나이스
bizplay 지역화폐 - 서울페이(비플)
card001 카드형 지역화폐 - 광주상생카드
card002 카드형 지역화폐 - 목포사랑카드
card003 카드형 지역화폐 - 세종시여민전카드
kakaopay 카카오페이 간편결제
naverpay 네이버페이 간편결제
fitcollabo 핏콜라보 앱카드 간편결제

오류코드

오류코드
HTTP 응답 코드 오류 코드 오류 메시지 비고
401 998 유효하지 않은 토큰입니다. 인증 오류
403 993 허용되지 않는 접근 요청입니다. 인증 오류
405 995 요청 메서드 권한이 없습니다. HTTP 메서드 오류
406 500 - 5000 오류 상세 메시지 비즈니스 논리 오류
500 999 내부 서버 오류 시스템 오류

카드사 코드 & 기관 코드

카드사 코드

카드사 코드
카드사 코드 카드사 명
S001 비씨(페이북)
S002 KB Pay(국민)
S003 하나
S004 삼성
S005 신한
S006 현대
S007 롯데
S008 NH
S009 씨티(구.한미)
S010 수협
S011 우리
S012 신협
S013 광주
S014 전북
S015 제주
S016 우체국
S017 MG새마을금고
S018 저축은행
S019 카카오뱅크

기관코드

기관코드
기관 코드 기관 명
002 KDB산업은행
003 IBK기업은행
004 KB국민은행
007 수협은행
011 NH농협은행
020 우리은행
023 SC제일은행
027 한국씨티은행
031 대구은행
032 부산은행
034 광주은행
035 제주은행
037 전북은행
039 경남은행
081 하나은행
088 신한은행
089 케이뱅크
090 카카오뱅크
092 토스뱅크
012 농협중앙회
071 우정사업본부
045 새마을금고중앙회
048 신협중앙회
050 저축은행중앙회
064 산림조합중앙회
218 KB증권
227 KTB투자증권
238 미래에셋증권
240 삼성증권
243 한국투자증권
247 NH투자증권
261 교보증권
262 하이투자증권
263 현대차증권
264 키움증권
265 이베스트투자증권
266 SK증권
267 대신증권
269 한화투자증권
270 하나금융투자
271 토스증권
278 신한금융투자
279 DB금융투자
280 유진투자증권
287 메리츠증권

인 앱 결제 연동 앱 스키마

O2O 플랫폼 인앱 결제를 진행하는 고객사에 설정이 필요한 앱 스키마 정보입니다. 아래 표의 앱 스키마 정보를 설정하지 않는 경우, 고객사 앱에서 인앱 결제 관련 앱으로의 전환 과정이 정상적이지 않을 수 있으니 주의가 필요합니다.

인앱 결제 연동

AOS

안드로이드 결제 시 안심클릭, 앱카드, ISP를 통한 결제 중 백신, 앱가드 앱 등을 실행하기 위한 처리가 필요합니다.
안드로이드 11(API 30) 패키지로 개발 및 업데이트 하는 경우 아래 두가지 방안 중 한 가지를 필수로 조치하시길 바랍니다.
1) <queries> 요소에 패키지 정의
     - AndroidManifest.xml 파일 수정
     - 매니페스트 파일의 <queries> 요소에 패키지를 정의하면 패키지의 가시성이 확보됩니다.
     - 카드사 및 백신의 패키지명은 첨부 파일을 참고하시길 바랍니다.
2) WebViewClient shouldOverrideUrlLoading() 예외처리 로직 추가
     - 재정의한 shouldOverrideUrlLoading() 메소드 로직 수정 필요
     - 앱 설치여부 확인을 위해 startActivity() 호출 전에 패키지 정보를 조회하는 경우, 설치 여부 확인 로직을 제거하고 바로 startActivity()을 호출
     - startActivity() 호출 시 ActivityNotFoundException (Message: No Activity found to handle Intent)이 발생한 경우 앱이 설치되지 않은 것으로 간주하고 앱 설치를 위해 마켓으로 이동하도록 처리
                                

iOS

REST API를 통해 결제 페이지의 URL을 받으신 후 결제창을 WEBVIEW 방식을 통해 여는 방법을 사용하시면 됩니다.
App-Schema 이슈발생 시 적용 할 수 있는 방법은 아래 두 가지 중 한가지로 적용하실 수 있습니다.
    1) info.plist 파일에 "LSApplicationQueriesSchemes" 배열내 스키마 목록 추가
    2) Xcode 에서 LSApplicationWueriesSchemes >item 항목에 결제 수단을 추가
                                

AOS 앱 스키마

AOS 앱 스키마
구분 앱 패키지 명 비고
신용카드 ottesmartpay 롯데모바일결제앱
lotteappcard 롯데카드-앱카드
shinhan-sr-ansimclick 신한카드-앱카드
Smshinhanansimclick 신한카드-공인인증서
Smshinhancardusim 신한카드
shinhan-sr-ansimclick-lpay 신한페이판-엘페이
shinhan-sr-ansimclick-naverpay 신한페이판-네이버페이
shinhan-sr-ansimclick-payco 신한페이판-페이코
shinhan-sr-ansimclick_samsungpay 신한페이판-삼성페이
shinhan-sr-ansimclick_lgpay 신한페이판-LG페이
Citimobile 씨티모바일앱 스마트간편결제
Citimobileapp 씨티카드-간편결제
Citispay 씨티카드-앱카드
Citicardappkr 씨티카드-공인인증서
Citicardapp 씨티카드 일반결제 - 공인인증서 관리앱
Ispmobile ISP결제앱
kb-acp 국민카드-앱카드
hdcardappcardansimclick 현대앱카드
Smhyundaiansimclick 현대카드 공인인증서 관리앱
mpocket.online.ansimclick 삼성카드 m포켓(앱카드)
Ansimclickscard 삼성카드-온라인결제
mpocket.ansimclick.cert 삼성 앱카드-공동인증서
Samsungpay 삼성카드-삼성페이
Scardcertiapp 삼성카드-공인인증서
Tswansimclick 삼성카드-온라인결제
Cloudpay 하나SK카드 모비페이
Hanamopmoasign 하나카드 공인인증앱
Hanaansim 하나SK카드 안심클릭
Hanawalletmembers 하나멤버스월렛
nonghyupcardansimclick 농협카드-공인인증서
Nhappcardansimclick 농협카드-앱카드
nhallonepayansimclick 농협카드-올원페이
nhappcash-acp 농협
v3mobileplusweb NH카드 - 백신(V3)
Wibeetalk  
Woorimembers 우리은행-위비멤버스
PortalCenterWB 우리은행-금융센터
SmartBank2WB 우리은행-원터치개인
SmartBank2WIB 우리은행-위비뱅크
Wooripay 우리페이
Wooribank 우리 WON
뱅킹  
Uppay 은련카드
bankwallet 뱅크월렛
kdb-bankpay 산업은행
ibk-bankpay 기업은행
kb-bankpay 국민은행
Liivbank LiiV(국민은행)
kb-event KBPay
kb-screen KBPay
Newliiv 리브 Next
kbbank KB스타뱅킹
lottecard  
appcard  
citispayapp  
인터넷뱅킹 kftc-bankpay 금융결제원 인터넷뱅킹
간편결제 payco  
lpayapp  
shinsegaeeasypayment SSGPAY
smilepayapp  
supertoss  
백신 ansimclickipcollect ansimclickipcollect
Vguardstart  
droidx3host  
Droidxantivirus 안심클릭 결제시 백신
Vguard 삼성카드, 신한카드, 씨티카드 사용 백신
Mvaccinestartbg TouchEn mVaccine (신한)
Mvaccineexit TouchEn mVaccine (신한)
Mvaccinecheck TouchEn mVaccine (신한)
Appfree 공동인증서
v3mobile  
Ansimclick  
market://details?id=com.shcard.smartpay  
http://m.ahnlab.com/kr/site/download  
https://m.ahnlab.com/kr/site/download  
Vguardcheck V-Guard (삼성)
Vguardend V-Guard (삼성)
Callonlinepay 엘지페이 (삼성, KB)
Mvaccine 백신
ahnlabv3mobileplus 롯데카드 사용 백신
Smartwal  
mvaccinestart 외환카드 사용 백신 변경
은행 keb-bankpay KEB하나은행
sh-bankpay 수협
nhb-bankpay 농협
nh-bankpay 농축협
wr-bankpay 우리은행
sc-bankpay SC은행
s-bankpay 신한은행
ct-bankpay 씨티은행
dg-bankpay 대구은행
bnk-bankpay 부산은행
kj-bankpay 광주은행
jj-bankpay 제주은행
jb-bankpay 전북은행
kn-bankpay 경남은행
kp-bankpay 우정사업본부
cu-bankpay 신협
mg-bankpay 새마을
kbn-bankpay K뱅크
kkb-bankpay 카카오뱅크
기타 .apk  
DroidXAntivirus.apk  
deeplink  
upapp  
intmoney  
http://market.android.com  
https://market.android.com  
MW_PUSH  
tel  
lmslpay 신규L.POINT APP
itms-apps 앱스토어
daumapps 다음
naversearchapp 네이버
googlechromes 크롬
onestore:// 원스토어

AOS 앱 패키지

AOS 앱 패키지
구분 App 패키지명 비고
신용카드 com.shcard.smartpay 신한카드
com.shinhancard.smartshinhan 신한카드
kr.co.samsungcard.mpocket 삼성카드
com.kbcard.cxh.appcard KB카드
com.kbstar.liivbank KB카드
com.kbstar.reboot KB카드 New Liib
nh.smart.nhallonepay NH카드
com.hyundaicard.appcard 현대카드
com.lge.lgpay 엘지페이 (삼성, KB)
com.wooricard.smartapp 우리 WON 뱅킹
com.wooribank.smart.npib 우리 WON 뱅킹
kvp.jjy.MispAndroid320 BC카드
com.hanaskcard.paycla 하나카드
kr.co.hanamembers.hmscustome 하나카드(멤버스결제)
com.lcacApp 롯데카드
kr.co.citibank.citimobile 씨티카드
com.shinhan.smartcaremgr 신한 슈퍼SOL
공인인증 com.hanaskcard.rocomo.potal 하나카드(인증)
com.lumensoft.touchenappfree 공동인증서
백신 com.TouchEn.mVaccine.webs TouchEn mVaccine
kr.co.shiftworks.vguardweb V-Guard
com.ahnlab.v3mobileplus V3
인터넷뱅킹 com.kftc.bankpay.android 금결원
간편결제 viva.republica.toss 토스
com.nhn.android.search 네이버페이
com.lottemembers.android 엘페이
com.ssg.serviceapp.android.egiftcertificate SSG페이
com.nhnent.payapp 페이코
com.kakao.talk 카카오페이
com.samsung.android.spay 삼성페이
com.samsung.android.spaylite 삼성페이 미니
com.mysmilepay.app 스마일페이
휴대폰결제 uplus.membership 휴대폰결제 (LGU)
선불카드 com.tmoney.inapp 티머니 인앱결제모듈
com.tmoney.nfc_pay 티머니 NFC
com.ebcard.cashbeeinapp 캐시비 인앱
본인인증 com.sktelecom.tauth KCB 휴대폰 본인인증 (SKT)
com.lguplus.smartotp KCB 휴대폰 본인인증 (LGU)
com.kt.ktauth KCB 휴대폰 본인인증 (KT)

iOS 앱 스키마

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>ispmobile</string>                                    <!--ISP모바일-->
    <string>kb-acp</string>                                        <!--국민카드-앱카드-->
    <string>liivbank</string>                                       <!--Liiv(KB국민은행)-->
    <string>newliiv</string>                                        <!--리브 Next-->
    <string>kbbank</string>                                       <!--KB스타뱅킹-->
    <string>hdcardappcardansimclick</string>                <!--현대카드-앱카드-->
    <string>smhyundaiansimclick</string>                     <!--현대카드-공인인증서-->
    <string>shinhan-sr-ansimclick</string>                     <!--신한카드-앱카드-->
    <string>smshinhanansimclick</string>                      <!--신한카드-공인인증서-->
    <string>smshinhancardusim</string>                       <!--신한카드-->
    <string>mpocket.online.ansimclick</string>               <!--삼성카드-앱카드-->
    <string>ansimclickscard</string>                            <!--삼성카드-온라인결제-->
    <string>ansimclickipcollect</string>                        <!--삼성카드-온라인결제-->
    <string>vguardstart</string>                                 <!--삼성카드-백신-->
    <string>samsungpay</string>                               <!--삼성카드-삼성페이-->
    <string>scardcertiapp</string>                              <!--삼성카드-공인인증서-->
    <string>tswansimclick</string>                              <!--삼성카드온라인결제-->
    <string>lottesmartpay</string>                              <!--롯데카드-모바일결제-->
    <string>lotteappcard</string>                               <!--롯데카드-앱카드-->
    <string>ahnlabv3mobileplus</string>                        <!--롯데카드사용백신-->
    <string>cloudpay</string>                                     <!--하나카드-앱카드-->
    <string>hanamopmoasign</string>                               <!--하나카드공인인증앱-->
    <string>hanaansim</string>                                    <!--하나SK카드안심클릭-->
    <string>hanawalletmembers</string>                            <!--하나멤버스월렛-->
    <string>nhappvardansimclick</string>                          <!--농협카드-앱카드-->
    <string>nonghyupcardansimclick</string>                       <!--농협카드-공인인증서-->
    <string>nhappcardansimclick</string>                          <!--농협카드앱카드-->
    <string>nhallonepayansimclick</string>                        <!--농협카드올원페이-->
    <string>nhappcash-acp</string>                                <!--농협-->
    <string>citispay</string>                                     <!--씨티카드-앱카드-->
    <string>citicardappkr</string>                                <!--씨티카드-공인인증서-->
    <string>citimobileapp</string>                                <!--씨티카드-간편결제-->
    <string>Wooripay</string>                                     <!--우리페이-->
    <string>com.wooricard.wcard</string>                          <!--우리WON-->

    <string>NewSmartPib</string>                             <!--우리WON뱅킹 앱-->
    <string>lmslpay</string>                                 <!--엘페이-->
    <string>supertoss</string>                               <!--토스-->
    <string>payco</string>                                   <!--페이코-->
    <string>kakaotalk</string>                               <!--카카오페이-->
    <string>naversearchapp</string>                          <!--네이버페이-->
    <string>shinsegaeeasypayment</string>                    <!--SSGPAY-->
    <string>callonlinepay</string>                           <!--LG페이-->

    <string>uppay</string>                                    <!--은련카드-->
    <string>mvaccinestart</string>                            <!--외환카드-->
    <string>citicardapp</string>                              <!--씨티카드일반결제-공인인증서관리앱-->
    <string>droidx3host</string>                              <!--백신-->
    <string>droidxantivirus</string>                          <!--안심클릭결제시백신설치또는실행(현대카드예)-->
    <string>vguard</string>                                   <!--삼성카드,신한카드,씨티카드사용백신-->
</array>

                                

ISP/페이북 결제연동 참고사항

MainActivity 구성

  1. 인증을 요청할 카드를 선택, 전자금융거래 이용약관 등의 동의 이후 ISP를 실행합니다 (*ISP 설치여부 체크 필요)
  2. ISP 인증 성공(또는 취소) 이후 콜백 화면에서 인증 처리 여부를 판단하고 적절한 화면을 표시합니다.

AndroidManifest.xml ISP 설정

ISP 처리 이후 인증을 요청했던 APP의 웹뷰로 콜백 결과를 전달받을 수 있도록, 결과 수신용 Activity에 아래와 같은 intent-filter를 설정합니다.

<activity
    android:name="com.spg.spgwebviewtest.MainResultActivity"
    android:label="@string/app_name" >
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="spgapptest" />
    </intent-filter>
</activity>

                                

MainActivity 구현

안내의 모바일 안전결제(ISP/페이북) 연동을 위해, 아래 TestWebViewClient 소스코드처럼 ISP 결제앱 설정이 필요합니다.

private class TestWebViewClient extents WebViewClient {
    @Override
    public boolean shouldOverrideUrlLoading (WebView view, String url) {
        mContext = MainActivity.this;

        if (url.contains("droidxantivirus")  //안심클릭 결제 시 백신 설치 또는 실행(현대카드 예)
            ... ...
            || url.contains("ispmobile")     //ISP 결제 앱
            ... ...
        ){ ... ...

                                

모바일 안전결제(ISP/페이북)으로부터 전달받은 URL을 아래와 같이 처리합니다.

// ISP 앱의 콜백(Callback)을 전달받기 위한 앱 스키마
private final String APP_SCHEME_URL = "spgapptest://";
// ISP 앱에서 취소 선택 시 URI
private final String APP_SCHEME_CANCEL_URL = APP_SCHEME_URL + "ISPCancel/";
// ISP 앱에서 인증 성공 시 URI
private final String APP_SCHEME_SUCCESS_URL = APP_SCHEME_URL + "ISPSuccess/";
… …
/*
* ISP로부터 전달받은 URI에 따라 결제 최종 확인 또는 결제 요청 이전의 페이지를 표시합니다.
* @param resultUrl ISP로부터 전달받은 URI
*/
private void getResultPage(Uri resultUri) {
    String schemaUrl = resultUri.toString();
    String urlString = null;

    if(schemaUrl.startsWith(APP_SCHEMA_SUCCESS_URI)){ //ISP 인증을 성공한 경우
        if(MainActivity.mContext != null){
            (Activity) MainActivity.mContext).finish();
        }
        urlString = schemaUrl.substring(APP_SCHEMA_SUCCESS_URI.length());
        mWvCardResultView.loadUrl(urlString);
    }else if(schemaUrl.startsWith(APP_SCHEMA_CANCEL_URI)){ //ISP앱에서 취소를 선택한 경우
        if(MainActivity.mContext != null){
            ((Activity) MainActivity.mContext).finish();
        }
        urlString = schemaUrl.substring(APP_SCHEMA_CANCEL_URI.length());
        mWvCardResultView.loadUrl(urlString);
    }
}