Version 1
웹뷰(WebView) 연동하기
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:// |
Android
먼저 AndroidManifest.xml 파일에 카드앱·은행앱 패키지를 등록합니다. 패키지를 등록하지 않으면 앱이 설치되어 있어도 스토어로 이동하고, Google 정책을 위반하게 됩니다.
AndroidManifest.xml 파일에 필요한 앱 스킴을 추가했다면, 앱 간 이동에 필요한 아래 코드를 살펴보세요.
WebViewClient의 shouldOverrideUrlLoading 함수에 오버라이딩 로직을 추가하세요.
추가하지 않으면 웹뷰에서 외부 앱을 호출하거나 마켓(market://)으로 연결할 때 net::ERR_UNKNOWN_URL_SCHEME 에러가 발생합니다.
위와 같이 구현하기 어려우면 패키지 공개 상태 관리 대응을 확인해보세요.
iOS
먼저 Info.plist 에 LSApplicationQueriesSchemes 를 추가하고 카드사, 은행의 앱 스킴을 배열에 넣어 주세요. 설정하지 않으면, 앱이 열리지 않고 콘솔 쪽에 canOpenURL : failed for URL 에러가 발생합니다.
XCode에 필요한 앱 스킴을 추가했다면, 앱 간(App to App) 이동에 필요한 아래 코드를 살펴보세요.
웹뷰에서 URL이 변경될 때 페이지 전환 대신 내 상점의 앱 스킴을 실행시키려면 WKNavigationDelegate protocol 중 아래 코드에 해당하는 메서드를 구현해야 합니다.
Flutter
플러그인 추가하기
pubspec.yaml 파일에 가장 최신 버전의 토스페이먼츠 플러그인을 추가해주세요.
webview_flutter를 사용하고 있다면 webview_flutter_android는 3.16.0 이하 버전만 사용해주세요. 이후 버전 부터는 안드로이드 환경에서 특정 카드앱이 호출되지 않는 문제가 발생합니다.
URL 변환하기
Flutter 웹뷰에서는 Intent URL을 앱 스킴 URL로 변환해야 카드사 앱으로 이동합니다. 아래 예시와 같이 tossPaymentsWebview() 함수를 정의해서 사용하세요.
ConvertUrl
- url
앱 스킴 형태로 변환하고 싶은 Intent 스킴 URL입니다. 예를 들어
intent:appScheme://...#Intent;...;end;형태의 Intent URL이appScheme://...형태의 앱 스킴 URL로 바뀝니다.
React Native
설치하기
npm 또는 yarn으로 토스페이먼츠 결제위젯 React Native SDK를 설치하세요.
URL 변환하기
React Native 웹뷰에서는 Intent URL을 앱 스킴 URL로 변환해야 카드사 앱으로 이동합니다. 아래 예시와 같이 urlConverter() 함수를 정의해서 사용하세요.
ConvertUrl
- url
앱 스킴 형태로 변환하고 싶은 Intent 스킴 URL입니다. 예를 들어
intent:appScheme://...#Intent;...;end;형태입니다. - appScheme
url의 앱스킴입니다. - appLink
url의 앱스킴 링크입니다. 예를 들어appScheme://...형태입니다. - package
url의 앱 패키지 정보입니다.