Version 1
SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.
✅ 모바일 웹뷰에서 카드 결제창으로 이동할 때 필요한 외부 앱(3rd-party 앱)을 연동하는 과정을 알 수 있어요.
✅ 연동에 필요한 외부 앱 스킴(App URL Scheme) 목록과 로직을 이해할 수 있어요.
웹뷰는 다음과 같이 사용할 수 있습니다.
- 주문 정보를 작성하고 결제창을 호출합니다.
- 카드사를 선택하고 다음 단계로 이동합니다.
- 선택한 카드사·은행의 결제 앱이 열립니다. 외부 앱이 실행되는 시점입니다.
- 결제 정보를 입력하고 결제를 완료합니다.
- 상점의 결제 페이지로 돌아옵니다.
- 앱 스킴(
appScheme
) 파라미터를 추가하면 별도의 처리 없이도 외부 앱에서 상점 앱으로 돌아올 수 있습니다. 결제 요청 파라미터를 참고하세요.
여기서는 3번 단계에서 외부 앱을 여는 방법을 다룹니다. 웹뷰에서 각 은행의 결제 앱을 실행시키면서 앱 간 일어나는 이동(App to App)입니다.
내 상점 앱에서 인증을 위해 이동하게 되는 3rd-party 앱에는 ISP 앱, 카드사별 앱카드 등이 있습니다. 이동할 앱 스킴 리스트를 보고 추가해보세요.
카드사·본인확인기관 | 앱 스킴 |
---|---|
토스페이 | supertoss:// |
국민카드 | kb-acp:// , liivbank:/ , newliiv:// , kbbank:// |
농협카드 | nhappcardansimclick:// , nhallonepayansimclick:// , nonghyupcardansimclick:// |
롯데카드 | lottesmartpay:// , lotteappcard:// |
삼성카드 | mpocket.online.ansimclick:// , vguardstart:// , samsungpay:// ,monimopay:// , monimopayauth:// |
신한카드 | shinhan-sr-ansimclick:// , smshinhanansimclick:// |
우리카드 | com.wooricard.wcard:// , newsmartpib:// |
씨티카드 | citispay:// , citicardappkr:// , citimobileapp:// |
하나카드 | cloudpay:// , hanawalletmembers:// |
현대카드 | hdcardappcardansimclick:// , smhyundaiansimclick:// |
간편결제 | shinsegaeeasypayment:// , payco:// , lpayapp:// |
ISP(BC/국민) | ispmobile:// |
먼저 AndroidManifest.xml
파일에 카드앱·은행앱 패키지를 등록합니다. 패키지를 등록하지 않으면 앱이 설치되어 있어도 스토어로 이동하고, Google 정책을 위반하게 됩니다.
AndroidManifest.xml
파일에 필요한 앱 스킴을 추가했다면, 앱 간 이동에 필요한 아래 코드를 살펴보세요.
WebViewClient의 shouldOverrideUrlLoading
함수에 오버라이딩 로직을 추가하세요.
추가하지 않으면 웹뷰에서 외부 앱을 호출하거나 마켓(market://
)으로 연결할 때 net::ERR_UNKNOWN_URL_SCHEME
에러가 발생합니다.
위와 같이 구현하기 어려우면 패키지 공개 상태 관리 대응을 확인해보세요.
먼저 Info.plist
에 LSApplicationQueriesSchemes 를 추가하고 카드사, 은행의 앱 스킴을 배열에 넣어 주세요. 설정하지 않으면, 앱이 열리지 않고 콘솔 쪽에 canOpenURL : failed for URL
에러가 발생합니다.
XCode에 필요한 앱 스킴을 추가했다면, 앱 간(App to App) 이동에 필요한 아래 코드를 살펴보세요.
웹뷰에서 URL이 변경될 때 페이지 전환 대신 내 상점의 앱 스킴을 실행시키려면 WKNavigationDelegate protocol 중 아래 코드에 해당하는 메서드를 구현해야 합니다.
pubspec.yaml
파일에 가장 최신 버전의 토스페이먼츠 플러그인을 추가해주세요.
webview_flutter
를 사용하고 있다면 webview_flutter_android
는 3.16.0 이하 버전만 사용해주세요. 이후 버전 부터는 안드로이드 환경에서 특정 카드앱이 호출되지 않는 문제가 발생합니다.
Flutter 웹뷰에서는 Intent URL을 앱 스킴 URL로 변환해야 카드사 앱으로 이동합니다. 아래 예시와 같이 tossPaymentsWebview()
함수를 정의해서 사용하세요.
- url
앱 스킴 형태로 변환하고 싶은 Intent 스킴 URL입니다. 예를 들어
intent:appScheme://...#Intent;...;end;
형태의 Intent URL이appScheme://...
형태의 앱 스킴 URL로 바뀝니다.
npm 또는 yarn으로 토스페이먼츠 결제위젯 React Native SDK를 설치하세요.
React Native 웹뷰에서는 Intent URL을 앱 스킴 URL로 변환해야 카드사 앱으로 이동합니다. 아래 예시와 같이 urlConverter()
함수를 정의해서 사용하세요.
- url
앱 스킴 형태로 변환하고 싶은 Intent 스킴 URL입니다. 예를 들어
intent:appScheme://...#Intent;...;end;
형태입니다. - appScheme
url
의 앱스킴입니다. - appLink
url
의 앱스킴 링크입니다. 예를 들어appScheme://...
형태입니다. - package
url
의 앱 패키지 정보입니다.