모바일 앱에서 결제 연동하기

pubspec.yaml
dependencies:
  flutter_inappwebview: ^6.1.5 # WebView
  url_launcher: ^6.3.1 # 외부 앱 실행

flutter pub get

Android의 WebView는 기본 제공되므로 별도 의존성이 필요하지 않습니다.

build.gradle에서 minSdk 21 이상을 확인하세요.

build.gradle.kts
android {
    defaultConfig {
        minSdk = 21
    }
}

iOS의 WKWebView는 WebKit 프레임워크에 기본 포함되어 있으므로 별도 의존성이 필요하지 않습니다.

배포 대상은 iOS 14 이상을 권장합니다.

react-native-webview로 WebView를 표시하고, Linking API로 외부 앱을 실행합니다.

npm install react-native-webview

iOS의 경우 추가로 Pod을 설치합니다.

cd ios && pod install

Flutter 프로젝트에서는 각 플랫폼의 네이티브 설정 파일에 직접 추가합니다.

• Android: android/app/src/main/AndroidManifest.xml — Android 탭의 queries 내용을 추가합니다.
• iOS: ios/Runner/Info.plist — iOS 탭의 LSApplicationQueriesSchemes와 CFBundleURLTypes 내용을 추가합니다.

Android 11(API 30) 이상에서는 패키지 가시성 정책에 따라 AndroidManifest.xml에 결제 앱 패키지를 선언해야 합니다.

AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <queries>
    <package android:name="com.kftc.bankpay.android" /> <!-- 뱅크페이 -->
    <package android:name="kvp.jjy.MispAndroid320" /> <!-- ISP / 페이북 -->
    <package android:name="com.hyundaicard.appcard" /> <!-- 현대카드 -->
    <package android:name="com.shcard.smartpay" /> <!-- 신한 SOL페이 -->
    <package android:name="com.shinhan.smartcaremgr" /> <!-- 신한 슈퍼SOL -->
    <package android:name="com.shinhan.sbanking" /> <!-- 신한 SOL뱅크 -->
    <package android:name="com.kbcard.cxh.appcard" /> <!-- KB Pay -->
    <package android:name="com.kbstar.kbbank" /> <!-- KB스타뱅킹 -->
    <package android:name="kr.co.samsungcard.mpocket" /> <!-- 삼성카드 -->
    <package android:name="com.samsung.android.spay" /> <!-- Samsung Wallet -->
    <package android:name="net.ib.android.smcard" /> <!-- monimo -->
    <package android:name="com.lcacApp" /> <!-- 디지로카 (롯데카드) -->
    <package android:name="com.lottemembers.android" /> <!-- L.POINT with L.PAY -->
    <package android:name="com.hanaskcard.paycla" /> <!-- 하나Pay (하나카드) -->
    <package android:name="nh.smart.nhallonepay" /> <!-- NH Pay -->
    <package android:name="kr.co.citibank.citimobile" /> <!-- 씨티모바일 -->
    <package android:name="com.kakao.talk" /> <!-- 카카오톡 (카카오페이) -->
    <package android:name="com.nhnent.payapp" /> <!-- PAYCO -->
    <package android:name="com.wooricard.smartapp" /> <!-- 우리카드 우리WON카드 -->
    <package android:name="com.wooribank.smart.npib" /> <!-- 우리은행 우리WON뱅킹 -->
    <package android:name="viva.republica.toss" /> <!-- 토스 -->
    <package android:name="com.nhn.android.search" /> <!-- 네이버 (네이버페이) -->
    <package android:name="com.kakaobank.channel" /> <!-- 카카오뱅크 -->
    <package android:name="com.ahnlab.v3mobileplus" /> <!-- V3 Mobile Plus -->
    <package android:name="com.TouchEn.mVaccine.webs" /> <!-- 터치엔 엠백신 -->
    <package android:name="com.sktelecom.tauth" /> <!-- PASS by SKT -->
    <package android:name="com.kt.ktauth" /> <!-- PASS by KT -->
    <package android:name="com.lguplus.smartotp" /> <!-- PASS by U+ -->
    <package android:name="com.mysmilepay.app" /> <!-- 스마일페이 -->
    <package android:name="com.ssg.serviceapp.android.egiftcertificate" /> <!-- SSGPAY -->
    <package android:name="com.hanabank.mzplatform" /> <!-- 아이부자 -->
    <package android:name="com.knb.psb" /> <!-- BNK경남은행 -->
    <package android:name="kr.ac.yonsei.idcard" /> <!-- 연세페이 -->
    <package android:name="jp.naver.line.android" /> <!-- LINE (LINE Pay) -->
    <package android:name="com.eg.android.AlipayGphone" /> <!-- Alipay -->
    <package android:name="hk.alipay.wallet" /> <!-- AlipayHK -->
    <package android:name="com.tencent.mm" /> <!-- WeChat -->
    <package android:name="com.globe.gcash.android" /> <!-- GCash -->
    <package android:name="th.co.truemoney.wallet" /> <!-- TrueMoney -->
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
    </intent>
  </queries>
</manifest>

앱이 외부 결제 앱에서 복귀할 수 있도록 커스텀 URL scheme도 등록합니다. 결제를 시작하는 Activity의 intent-filter에 앱의 URL scheme을 추가합니다.

AndroidManifest.xml
<application ...>
  <activity
    android:name=".MainActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <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="myapp" />
    </intent-filter>
  </activity>
</application>

Info.plist에 LSApplicationQueriesSchemes를 등록하여 결제 앱의 URL scheme을 선언해야 합니다. iOS 15 이상에서는 최대 50개까지 등록할 수 있으므로, 필요한 항목만을 추가합니다.

Info.plist
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>kftc-bankpay</string> <!-- 뱅크페이 -->
  <string>ispmobile</string> <!-- ISP / 페이북 -->
  <string>hdcardappcardansimclick</string> <!-- 현대카드 -->
  <string>shinhan-sr-ansimclick</string> <!-- 신한 SOL페이 -->
  <string>shinhan-sr-ansimclick-payco</string> <!-- 신한 SOL페이 (PAYCO) -->
  <string>shinhan-sr-ansimclick-lpay</string> <!-- 신한 SOL페이 (L.PAY) -->
  <string>kb-acp</string> <!-- KB Pay -->
  <string>kbbank</string> <!-- KB스타뱅킹 -->
  <string>mpocket.online.ansimclick</string> <!-- 삼성카드 -->
  <string>lotteappcard</string> <!-- 디지로카 (롯데카드) -->
  <string>lmslpay</string> <!-- L.POINT with L.PAY -->
  <string>cloudpay</string> <!-- 하나Pay (하나카드) -->
  <string>nhallonepayansimclick</string> <!-- NH Pay -->
  <string>citimobileapp</string> <!-- 씨티모바일 (씨티카드) -->
  <string>kakaotalk</string> <!-- 카카오톡 (카카오페이) -->
  <string>payco</string> <!-- PAYCO -->
  <string>com.wooricard.wcard</string> <!-- 우리카드 우리WON카드 -->
  <string>newsmartpib</string> <!-- 우리은행 우리WON뱅킹 -->
  <string>supertoss</string> <!-- 토스 -->
  <string>naversearchthirdlogin</string> <!-- 네이버 (네이버페이) -->
  <string>kakaobank</string> <!-- 카카오뱅크 -->
  <string>tauthlink</string> <!-- PASS by SKT -->
  <string>ktauthexternalcall</string> <!-- PASS by KT -->
  <string>upluscorporation</string> <!-- PASS by U+ -->
  <string>kn-bankpay</string> <!-- BNK경남은행 -->
  <string>yonseipay</string> <!-- 연세페이 -->
  <string>line</string> <!-- LINE (LINE Pay) -->
  <string>alipays</string> <!-- Alipay -->
  <string>alipayhk</string> <!-- AlipayHK -->
  <string>weixin</string> <!-- WeChat -->
  <string>ascendmoney</string> <!-- TrueMoney -->
</array>

앱이 외부 결제 앱에서 복귀할 수 있도록 커스텀 URL scheme도 등록합니다.

Info.plist
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

React Native 프로젝트에서는 각 플랫폼의 네이티브 설정 파일에 직접 추가합니다.

• Android: android/app/src/main/AndroidManifest.xml — Android 탭의 queries 내용을 추가합니다.
• iOS: ios/<프로젝트명>/Info.plist — iOS 탭의 LSApplicationQueriesSchemes와 CFBundleURLTypes 내용을 추가합니다.

InAppWebView의 shouldOverrideUrlLoading 콜백에서 URL scheme별로 분기합니다.
전체 동작하는 예시는 portone_flutter SDK의 portone_webview.dart를 참고하세요.

InAppWebView(
  initialSettings: InAppWebViewSettings(
    useShouldOverrideUrlLoading: true,
    resourceCustomSchemes: ["intent"],
  ),
  shouldOverrideUrlLoading: (controller, navigateAction) async {
    // URI 파서는 플랫폼마다 동작이 다를 수 있으므로 (예: 페이북),
    // rawValue에서 직접 protocol을 추출합니다.
    final uri = navigateAction.request.url!.rawValue;
    var protocol = uri.substring(0, uri.indexOf(':'));

    switch (protocol) {
      case 'http':
      case 'https':
        return NavigationActionPolicy.ALLOW;
      case 'myapp':
        // 결제 완료 — 쿼리 파라미터에서 결과 추출
        return NavigationActionPolicy.CANCEL;
      case 'intent':
        // intent:// URI에서 scheme을 추출하여 앱 실행
        // 미설치 시 마켓으로 이동
        return NavigationActionPolicy.CANCEL;
      default:
        // PG/카드사 앱 등 외부 앱 실행
        if (await canLaunchUrlString(uri)) launchUrlString(uri);
        return NavigationActionPolicy.CANCEL;
    }
  },
)

WebViewClient의 shouldOverrideUrlLoading에서 URL scheme별로 분기합니다.
전체 구현은 Android SDK의 PortOneWebView.kt를 참고하세요.

webView.settings.javaScriptEnabled = true

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView, request: WebResourceRequest
    ): Boolean {
        val url = request.url
        return when (url.scheme) {
            "http", "https" -> false // WebView에서 정상 로드
            "myapp" -> {
                // 결제 완료 — 쿼리 파라미터에서 결과 추출
                handlePaymentResult(url)
                true
            }
            "intent" -> {
                // Intent URI 파싱 후 앱 실행, 미설치 시 마켓 이동
                launchIntentOrMarket(url)
                true
            }
            else -> {
                // PG/카드사 앱 등 외부 앱 실행
                startActivity(Intent(Intent.ACTION_VIEW, url))
                true
            }
        }
    }
}

WKNavigationDelegate의 decidePolicyFor에서 URL scheme별로 분기합니다.
전체 구현은 iOS SDK의 PaymentWebView.swift를 참고하세요.

func webView(
    _ webView: WKWebView,
    decidePolicyFor navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
) {
    guard let url = navigationAction.request.url else {
        decisionHandler(.allow)
        return
    }

    switch url.scheme {
    case "http", "https":
        decisionHandler(.allow)
    case "myapp":
        // 결제 완료 — 쿼리 파라미터에서 결과 추출
        handlePaymentResult(url: url)
        decisionHandler(.cancel)
    default:
        // PG/카드사 앱 등 외부 앱 실행
        UIApplication.shared.open(url)
        decisionHandler(.cancel)
    }
}

react-native-webview의 onShouldStartLoadWithRequest에서 URL scheme별로 분기합니다.
전체 구현은 React Native SDK의 SdkDelegate.tsx를 참고하세요.

import { Linking } from "react-native";
import { WebView } from "react-native-webview";

<WebView
  source={{ html: paymentHtml }}
  originWhitelist={["*"]}
  javaScriptEnabled
  onShouldStartLoadWithRequest={(request) => {
    const url = request.url;
    const protocol = url.split(":", 2)[0];

    switch (protocol) {
      case "http":
      case "https":
        return true;
      case "myapp":
        // 결제 완료 — 쿼리 파라미터에서 결과 추출
        handlePaymentResult(url);
        return false;
      case "intent":
        // intent:// URI에서 scheme을 추출하여 앱 실행
        // 미설치 시 마켓으로 이동
        launchIntentOrMarket(url);
        return false;
      default:
        // PG/카드사 앱 등 외부 앱 실행
        Linking.openURL(url).catch(() => {});
        return false;
    }
  }}
/>;