React Native 앱에 결제를 붙이려 할 때 가장 먼저 떠오르는 건 토스페이먼츠입니다. 국내 PG 중 React Native SDK를 공식으로 제공하는 곳이 드문 편인데, 토스페이먼츠는 @tosspayments/widget-sdk-react-native 패키지를 직접 관리하고 있습니다. 다만 내부 동작은 WebView 기반이고, Expo Managed Workflow에서는 추가 설정이 필요합니다. 이 글은 직접 연동하면서 확인한 내용을 정리한 것입니다.

토스페이먼츠 React Native SDK는 공식으로 있나요?

있습니다. @tosspayments/widget-sdk-react-native가 공식 패키지입니다. 토스페이먼츠 개발자센터에서 직접 문서를 제공하고 있고, 2025년 기준으로 버전 1.x 계열이 안정적으로 유지되고 있습니다.

단, 이 SDK는 내부적으로 react-native-webview를 통해 결제 UI를 렌더링합니다. 네이티브 결제 모듈이 아니라 WebView 래퍼에 가깝습니다. iOS의 WKWebView, Android의 WebView 안에서 결제창이 뜨는 구조입니다.

토스페이먼츠는 별도로 SDK v2도 발표했는데, v2는 웹/서버 연동에 초점이 맞춰져 있고 React Native 전용 SDK는 아직 v1 계열이 주력입니다. 신규 프로젝트라면 v1 기준으로 시작해도 무방합니다.

설치와 Expo 호환성

npm install @tosspayments/widget-sdk-react-native
npm install react-native-webview

피어 디펜던시로 react-native-webview >=13.3.0 <14.0.0이 필요합니다. 14.x는 아직 공식 지원 범위 밖입니다.

공식 요구사항은 다음과 같습니다.

항목	최소 버전
React Native	0.76+
React	18.3+
Node.js	18+
Android API Level	24+
Java	11+

Expo Managed Workflow에서는 react-native-webview가 기본 포함되어 있지 않아 expo install react-native-webview 후 prebuild(또는 EAS Build)가 필요합니다. Bare Workflow는 별도 처리 없이 바로 쓸 수 있습니다. SDK 공식 문서에는 Expo 관련 언급이 없으니, Managed 환경에서 쓴다면 이 점을 미리 확인해야 합니다.

결제 요청 플로우

결제 흐름은 세 단계입니다.

1. PaymentWidgetProvider로 앱을 감싸고 clientKey와 customerKey를 초기화
2. PaymentMethodWidget과 AgreementWidget으로 결제 UI 렌더링
3. requestPayment()로 결제 실행 → 백엔드에서 paymentKey로 최종 승인

import {
  PaymentWidgetProvider,
  usePaymentWidget,
  PaymentMethodWidget,
  AgreementWidget,
} from '@tosspayments/widget-sdk-react-native';

function CheckoutScreen() {
  const paymentWidget = usePaymentWidget();

  const handlePayment = async () => {
    try {
      const result = await paymentWidget.requestPayment({
        orderId: 'order_unique_id_123456',
        orderName: '테스트 상품',
        customerName: '홍길동',
        customerEmail: 'test@example.com',
        appScheme: 'myapp://',
      });
      await confirmPayment(result.paymentKey, result.orderId, result.amount);
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <>
      <PaymentMethodWidget selector="payment-methods" />
      <AgreementWidget selector="agreement" />
      <Button title="결제하기" onPress={handlePayment} />
    </>
  );
}

export default function App() {
  return (
    <PaymentWidgetProvider
      clientKey="test_ck_YOUR_CLIENT_KEY"
      customerKey="user_unique_key"
    >
      <CheckoutScreen />
    </PaymentWidgetProvider>
  );
}

appScheme은 카카오페이, 토스 앱 등 외부 앱에서 결제 완료 후 돌아오는 딥링크 주소입니다. 이걸 빠뜨리면 외부 앱 결제 후 원래 앱으로 돌아오지 못합니다. Expo에서는 app.json의 scheme 값을 그대로 넣으면 됩니다.

실제 걸림돌과 해결 사례

1. react-native-webview 버전 충돌

13.x를 쓰다가 14.x로 업그레이드하면 SDK가 동작을 멈춥니다. 공식 지원 범위는 >=13.3.0 <14.0.0입니다. package.json에서 버전을 고정해두는 것이 안전합니다.

2. appScheme 누락으로 외부 앱 복귀 실패

카카오페이나 삼성페이 결제 후 앱으로 돌아오지 못하는 사례가 많습니다. appScheme 파라미터를 빠뜨리지 말고, iOS Info.plist의 LSApplicationQueriesSchemes에 관련 스킴도 등록해야 합니다.

3. Android 백버튼 처리

WebView 내에서 결제 진행 중 Android 뒤로가기를 누르면 결제창이 닫히는 대신 WebView 히스토리를 이동합니다. BackHandler로 WebView의 goBack()을 가로채는 처리가 필요합니다.

4. 결제 승인은 반드시 백엔드에서

requestPayment()가 반환하는 paymentKey는 클라이언트에서 최종 승인하면 안 됩니다. 반드시 서버에서 토스페이먼츠 /v1/payments/confirm API를 호출해야 합니다. 클라이언트에서 직접 호출하면 Secret Key 노출 위험이 있습니다.

WebView 방식 vs 서버사이드 직접 연동

토스페이먼츠 공식 SDK는 WebView 방식입니다. 순수 네이티브 결제 UI는 제공하지 않습니다. 일부 개발자들이 @tosspayments/payment-widget-sdk(웹 SDK)를 React Native WebView 안에 직접 로드하는 방식으로 사용하기도 하는데, 이 경우 유지보수 부담이 커집니다. 공식 @tosspayments/widget-sdk-react-native를 쓰는 것이 낫습니다.

풀스택 보일러플레이트에서 결제 연동을 처음부터 구성한다면, NestJS 백엔드에 승인 엔드포인트를 미리 만들어두고 클라이언트는 paymentKey 전달만 담당하도록 역할을 분리하는 구조가 깔끔합니다.