카카오페이를 React Native 앱에 붙이려 하면 첫 번째 장벽부터 만납니다. 공식 React Native SDK가 없습니다. 카카오는 Android, iOS, Flutter SDK를 공식 제공하지만, React Native는 별도 패키지 없이 WebView와 REST API를 조합해서 직접 구현해야 합니다. 번거롭지만 구조를 한 번 잡아두면 이후 유지보수는 어렵지 않습니다.

카카오페이 React Native 공식 SDK는 없나요?

2026년 현재도 없습니다. 카카오페이 개발자센터(developers.kakaopay.com)는 REST API 기반 온라인결제 API만 제공합니다. React Native 앱에서 카카오페이를 사용하는 표준 방법은 두 가지입니다.

1. 카카오페이 온라인결제 API 직접 연동: 서버에서 결제 준비 API를 호출하고, 앱에서 next_redirect_app_url을 WebView로 열어 결제 진행 후 딥링크로 복귀
2. 토스페이먼츠 결제위젯 우회 연동: 토스페이먼츠 결제위젯에 카카오페이 결제수단이 포함되어 있어, 토스페이먼츠 SDK 하나로 카카오페이를 포함한 여러 결제수단을 한 번에 처리 가능

1인 개발자라면 2번이 훨씬 빠릅니다. 카카오페이만 단독 결제수단으로 지원해야 한다면 직접 연동을 선택하게 됩니다.

카카오페이 온라인결제 API 구조

결제 플로우는 준비(ready) → 사용자 인증 → 승인(approve) 세 단계입니다.

결제 준비 API

const response = await fetch('https://open-api.kakaopay.com/online/v1/payment/ready', {
  method: 'POST',
  headers: {
    Authorization: `SECRET_KEY ${process.env.KAKAO_PAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    cid: 'TC0ONETIME',
    partner_order_id: 'order_001',
    partner_user_id: 'user_001',
    item_name: '테스트 상품',
    quantity: 1,
    total_amount: 10000,
    tax_free_amount: 0,
    approval_url: 'https://yourapp.com/payment/success',
    cancel_url: 'https://yourapp.com/payment/cancel',
    fail_url: 'https://yourapp.com/payment/fail',
  }),
});

const data = await response.json();

API 엔드포인트는 2024년 초에 https://kapi.kakao.com/v1/payment/ready에서 https://open-api.kakaopay.com/online/v1/payment/ready로 변경됐습니다. 구 URL을 쓰는 레거시 코드라면 반드시 업데이트해야 합니다. 인증 헤더 키도 KakaoAK에서 SECRET_KEY로 바뀌었습니다.

React Native 앱에서 WebView로 결제 진행

서버에서 받은 next_redirect_app_url을 React Native WebView로 열면 카카오페이 결제 화면이 뜹니다.

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

function KakaoPayScreen({ redirectAppUrl }: { redirectAppUrl: string }) {
  return (
    <WebView
      source={{ uri: redirectAppUrl }}
      onShouldStartLoadWithRequest={(request) => {
        const { url } = request;
        if (url.startsWith('intent://') || url.startsWith('kakaotalk://')) {
          Linking.openURL(url).catch(() => null);
          return false;
        }
        if (url.startsWith('myapp://payment/success')) {
          handlePaymentSuccess(url);
          return false;
        }
        return true;
      }}
    />
  );
}

Android와 iOS에서 다른 두 가지 문제

Android: intent scheme URL 처리

Android에서 카카오톡 앱을 여는 URL은 intent://kakaopay/pg?url=...#Intent;scheme=kakaotalk;package=com.kakao.talk;end 형식입니다. react-native-webview는 이 URL을 기본적으로 처리하지 못해 "Can't open url" 에러가 납니다. onShouldStartLoadWithRequest에서 intent://로 시작하는 URL을 잡아서 Linking.openURL()로 넘기는 처리가 필수입니다.

iOS: onMessage 충돌

iOS 환경에서 WebView에 onMessage props를 등록하면 카카오페이 결제창이 열리지 않는 문제가 2024년 하반기부터 보고되고 있습니다. 카카오페이 브릿지 페이지 변경 이후 발생하는 이슈로, 결제 URL로 진입하는 시점에 onMessage를 undefined로 교체하는 임시 해결책이 사용되고 있습니다.

파트너 가입 없이 테스트할 수 있나요?

가능합니다. 카카오페이 개발자센터(developers.kakaopay.com)에서 카카오 계정으로 가입하고 애플리케이션을 등록하면 Secret Key를 발급받을 수 있습니다. 테스트용 CID TC0ONETIME(단건)과 TCSUBSCRIP(정기)을 사용하면 실제 결제 없이 플로우를 확인할 수 있습니다.

실제 결제를 받으려면 카카오페이 파트너센터(partner.kakaopay.com)에 사업자로 등록해야 합니다. 개인사업자 또는 법인 모두 가능하지만, 사업자 없이 순수 개인으로는 실제 결제 처리가 불가능합니다.

카카오페이 단독 연동 vs 토스페이먼츠 우회

1인 개발자가 앱에 결제를 붙일 때 실용적인 선택 기준은 하나입니다. "카카오페이만 받을 건가, 여러 결제수단을 받을 건가."

카카오페이 결제수단 비중이 높은 서비스라도 직접 연동보다 토스페이먼츠 결제위젯을 쓰면 카카오페이를 포함해 신용카드, 간편결제 전체를 한 SDK로 처리할 수 있습니다. 유지보수 포인트가 하나로 줄어들고, API 엔드포인트 변경 같은 이슈도 SDK가 흡수합니다.