개발 전 확인이 필요한 공통적인 가이드
고객사 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 데이터를 응답합니다.
{
“date”: “응답 데이터",
“ret_code”: 응답 코드,
“ret_msg”: “응답 메시지"
}
Http Status Code 200 응답은 성공, 그 외 모든 값(200이 아닌 값)은 실패를 의미합니다. 요청 처리 실패 시 반환되는 error 오브젝트 메시지를 반드시 확인해야 합니다. 고객사의 fall_url 이동 시, 요청 처리 실패에 대한 ret_code, ret_msg 정보가 POST 데이터로 반환됩니다.
200: OK
{
“date”: “응답 데이터",
“ret_code”: 응답 코드,
“ret_msg”: “응답 메시지"
}
400: Bad Request
{
“ret_code”: 응답 코드,
“ret_msg”: “응답 메시지"
}
고객사 계약 후 발급되는 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 플랫폼 인앱 결제를 진행하는 고객사에 설정이 필요한 앱 스키마 정보입니다. 아래 표의 앱 스키마 정보를 설정하지 않는 경우, 고객사 앱에서 인앱 결제 관련 앱으로의 전환 과정이 정상적이지 않을 수 있으니 주의가 필요합니다.
안드로이드 결제 시 안심클릭, 앱카드, ISP를 통한 결제 중 백신, 앱가드 앱 등을 실행하기 위한 처리가 필요합니다.
안드로이드 11(API 30) 패키지로 개발 및 업데이트 하는 경우 아래 두가지 방안 중 한 가지를 필수로 조치하시길 바랍니다.
1) <queries> 요소에 패키지 정의
- AndroidManifest.xml 파일 수정
- 매니페스트 파일의 <queries> 요소에 패키지를 정의하면 패키지의 가시성이 확보됩니다.
- 카드사 및 백신의 패키지명은 첨부 파일을 참고하시길 바랍니다.
2) WebViewClient shouldOverrideUrlLoading() 예외처리 로직 추가
- 재정의한 shouldOverrideUrlLoading() 메소드 로직 수정 필요
- 앱 설치여부 확인을 위해 startActivity() 호출 전에 패키지 정보를 조회하는 경우, 설치 여부 확인 로직을 제거하고 바로 startActivity()을 호출
- startActivity() 호출 시 ActivityNotFoundException (Message: No Activity found to handle Intent)이 발생한 경우 앱이 설치되지 않은 것으로 간주하고 앱 설치를 위해 마켓으로 이동하도록 처리
REST API를 통해 결제 페이지의 URL을 받으신 후 결제창을 WEBVIEW 방식을 통해 여는 방법을 사용하시면 됩니다.
App-Schema 이슈발생 시 적용 할 수 있는 방법은 아래 두 가지 중 한가지로 적용하실 수 있습니다.
1) info.plist 파일에 "LSApplicationQueriesSchemes" 배열내 스키마 목록 추가
2) Xcode 에서 LSApplicationWueriesSchemes >item 항목에 결제 수단을 추가
| 구분 | 앱 패키지 명 | 비고 |
|---|---|---|
| 신용카드 | 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:// | 원스토어 |
| 구분 | 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) |
<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 처리 이후 인증을 요청했던 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>
안내의 모바일 안전결제(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);
}
}