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:// |
| 카카오뱅크 | kakaobank:// |
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의 앱 패키지 정보입니다.