웹뷰 결제 | Bootpay 결제 매뉴얼

앱의 웹뷰에서 웹 기반 결제를 제공할 때 사용해요.

왜 부트페이 웹뷰를 써야 하나요?

국내 결제 환경에서는 카드사 본인인증 앱 호출, 간편결제 앱 전환, 팝업 처리 등 네이티브 앱과의 연동이 필수예요. 플랫폼 기본 WebView(WKWebView, android.webkit.WebView)는 이런 처리가 되어 있지 않아, 결제 진행 중 앱 호출이 실패하거나 결제 후 복귀가 안 되는 문제가 발생해요.

부트페이 웹뷰는 이러한 국내 결제 환경에 맞게 URL Scheme 처리, Intent 처리, 팝업 제어 등이 미리 구현되어 있어, 별도 설정 없이 기본 WebView를 교체하는 것만으로 결제가 정상 동작해요.

부트페이 웹뷰의 WebViewClient(Android)나 WKNavigationDelegate(iOS)를 임의로 오버라이드하면 결제 앱 호출·복귀 처리가 깨질 수 있어요. 부트페이 웹뷰를 그대로 사용해요.

웹뷰 결제 연동 전에, 먼저 웹에서 부트페이 JavaScript SDK로 결제 연동이 완료되어 있어야 해요.

2SDK 설치하기

사용하는 모바일 플랫폼에 맞게 부트페이 웹뷰 SDK를 설치해요.

PG 결제창 연동 → SDK 설치를 먼저 완료해요.

3웹뷰 적용하기

기존 WebView 대신 BootpayWebView를 사용하여 웹 서비스를 연결해요.

import kr.co.bootpay.android.webview.BootpayWebView

val webView = findViewById<BootpayWebView>(R.id.webview)
webView.loadUrl("https://www.yourdomain/payment/") //link your domainkotlin

import Bootpay

class WebAppController: UIViewController {
    let webview = BootpayWebView()
    webview.webview.frame = CGRect(x: 0,
                                   y: 0,
                                   width: UIScreen.main.bounds.width,
                                   height: UIScreen.main.bounds.height)
    let urlString = "https://www.yourdomain.com/"

    if let url = URL(string: urlString) {
        webview.webview.load(URLRequest(url: url))
    }

    self.view.addSubview(webview)
}swift

import 'package:bootpay/config/bootpay_config.dart';
import 'package:flutter/material.dart';
import 'package:bootpay_webview_flutter/bootpay_webview_flutter.dart';
import 'package:bootpay_webview_flutter_android/bootpay_webview_flutter_android.dart';
import 'package:bootpay_webview_flutter_wkwebview/bootpay_webview_flutter_wkwebview.dart';

class WebAppPayment extends StatefulWidget {
  const WebAppPayment();

  @override
  State<WebAppPayment> createState() => _WebAppPaymentState();
}

class _WebAppPaymentState extends State<WebAppPayment> {
  late final WebViewController _controller;

  @override
  void initState() {
    super.initState();

    late final PlatformWebViewControllerCreationParams params;
    if (WebViewPlatform.instance is BTWebKitWebViewPlatform) {
      params = WebKitWebViewControllerCreationParams(
        allowsInlineMediaPlayback: true,
        mediaTypesRequiringUserAction: const <PlaybackMediaTypes>{},
      );
    } else {
      params = const PlatformWebViewControllerCreationParams();
    }

    final WebViewController controller =
        WebViewController.fromPlatformCreationParams(params);

    controller
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setBackgroundColor(const Color(0x00000000))
      ..setNavigationDelegate(
        NavigationDelegate(
          onProgress: (int progress) {
            debugPrint('WebView is loading (progress : $progress%)');
          },
          onPageStarted: (String url) {
            debugPrint('Page started loading: $url');
          },
          onPageFinished: (String url) {
            debugPrint('Page finished loading: $url');
          },
          onWebResourceError: (WebResourceError error) {
            debugPrint('Received WebResourceError: $error');
          },
          onNavigationRequest: (NavigationRequest request) {
            return NavigationDecision.navigate;
          },
        ),
      )
      ..loadRequest(Uri.parse('https://www.yourdomain.com/')); // your website url

    if (controller.platform is AndroidWebViewController) {
      AndroidWebViewController.enableDebugging(true);
      (controller.platform as AndroidWebViewController)
          .setMediaPlaybackRequiresUserGesture(false);
    }

    _controller = controller;
  }

  @override
  Widget build(context) {
    return Scaffold(
      backgroundColor: Colors.green,
      body: SafeArea(child: platformWebViewWidget()),
    );
  }

  Widget platformWebViewWidget() {
    if (_controller.platform is AndroidWebViewController &&
        BootpayConfig.DISPLAY_WITH_HYBRID_COMPOSITION) {
      return WebViewWidget.fromPlatformCreationParams(
        params: AndroidWebViewWidgetCreationParams
            .fromPlatformWebViewWidgetCreationParams(
          AndroidWebViewWidgetCreationParams(
            controller: _controller.platform,
          ),
          displayWithHybridComposition: true,
        ),
      );
    }
    return WebViewWidget(controller: _controller);
  }
}dart

import React, {Component} from 'react';
import {View} from 'react-native';

import WebView from 'react-native-webview-bootpay';

type Props = {};
type State = {};

export default class Example extends Component<Props, State> {
    state = {};

    render() {
        return (
            <View style={{ flex: 1 }}>
                <WebView
                    enableApplePay={true}
                    source={{uri: "https://www.yourdomain.com/payment/"}}
                    automaticallyAdjustContentInsets={false}
                />
            </View>
        );
    }
}jsx

4참고 자료

각 플랫폼의 전체 예제 코드와 상세 문서를 확인할 수 있어요.

플랫폼	패키지 저장소	GitHub
Android	Maven Central	bootpay/android
iOS	CocoaPods	bootpay/ios
Flutter	pub.dev	bootpay/bootpay_flutter
React Native	npm	bootpay/react-native-bootpay

더 읽을거리

결제 체크아웃 설계 — 체크아웃 UI·에러 흐름
런칭 런북 — 웹뷰·앱 결제 런칭 체크리스트