Skip to main content

Quick Start

모바일 결제 통합을 4단계로 쉽게 시작하세요

Platform Examples

Android, iOS, React Native 및 Flutter용 전체 코드 예제
Dodo Payments는 Android, iOS, React Native 및 Flutter용 공식 checkout SDK를 제공합니다. 각 SDK는 아래에 설명된 패턴(checkout URL 열기, 반환값 캡처, 결과 파싱)을 단일 타입 지정 start(...) 호출 뒤에 래핑하며, abandoned-session recovery가 기본 제공됩니다. 사용 중인 스택에 맞는 SDK가 없는 경우에만 수동 WebView를 사용하세요.

사전 요구 사항

Dodo Payments를 모바일 앱에 통합하기 전에 다음 항목을 준비했는지 확인하세요:
  • Dodo Payments 계정: API access가 활성화된 merchant 계정
  • API Credentials: 대시보드에서 발급한 API key 및 webhook secret key
  • Mobile App Project: Android, iOS, React Native 또는 Flutter 애플리케이션
  • Backend Server: checkout session을 안전하게 생성하기 위한 서버

통합 워크플로

모바일 통합은 backend에서 API 호출을 처리하고 모바일 앱에서 사용자 경험을 관리하는 안전한 4단계 프로세스를 따릅니다.
1

Backend: Create Checkout Session

Checkout Session API Docs

Node.js, Python 등을 사용해 backend에서 checkout session을 생성하는 방법을 알아보세요. 전체 예제와 parameter reference는 전용 Checkout Sessions API documentation에서 확인할 수 있습니다.
Security: checkout session은 모바일 앱이 아닌 backend server에서만 생성해야 합니다. 이를 통해 API key를 보호하고 올바른 validation을 보장할 수 있습니다.
2

Mobile: Get Checkout URL

모바일 앱은 backend를 호출해 checkout URL을 가져옵니다. 이 요청은 로그인한 사용자의 고유 session token으로 인증하세요.
Security: 모바일 앱은 Dodo Payments API와 직접 통신하지 않고 backend와만 통신합니다.
3

Mobile: Open Checkout in Browser

결제 처리를 위해 안전한 인앱 브라우저에서 checkout URL을 여세요. 또는 플랫폼용 공식 checkout SDK를 사용해 수동 설정을 완전히 생략할 수 있습니다.

Pick your mobile SDK

Android, iOS, React Native 및 Flutter의 설치 단계와 설정 지침입니다.
4

Backend: Handle Payment Completion

webhook과 redirect URL을 통해 결제 완료를 처리하고 payment status를 확인합니다.

SDK 선택

모든 모바일 SDK는 동일한 contract를 제공합니다. 하나의 start(...) 호출로 플랫폼의 native browser surface에서 Dodo의 hosted checkout을 열고, 타입이 지정된 CheckoutResult를 반환합니다. 이 값의 statussucceeded, failed, cancelled, pending 또는 expired입니다. 어떤 SDK도 API key를 보유하거나 Dodo Payments API를 호출하지 않으며, 네 SDK 모두 abandoned-session recovery를 지원합니다.

Android

com.dodopayments.api:checkout-android는 Chrome Custom Tab을 엽니다. minSdk 23이 필요합니다.

iOS

dodopayments-mobile-sdk-iosSFSafariViewController를 엽니다. iOS 16 이상이 필요합니다.

React Native

@dodopayments/react-native-checkout는 두 native core 위에서 동작하는 Turbo Module입니다. React Native 0.76 이상이 필요합니다.

Flutter

dodopayments_checkout는 두 native core 위에서 동작하는 Pigeon channel입니다. Flutter 3.44 이상이 필요합니다.
반환되는 status는 결제 증명이 아닌 UI hint입니다. 모든 결제는 backend에서 payment.succeeded / subscription.active webhook을 통해 확인하거나 secret key로 payment를 조회해야 합니다.

Callback URL Scheme 등록

네 SDK 모두 사용자가 선택한 custom URL scheme을 통해 제어권을 앱으로 돌려보냅니다. 예를 들어 myapp://checkout/return와 같이 설정할 수 있습니다. 플랫폼별로 한 번씩 등록하세요:
android/app/build.gradle
SDK 자체의 manifest에는 redirect activity가 이미 선언되어 있으므로 추가할 manifest XML이 없습니다.
직접 구현하고 싶으신가요? checkout_url를 WebView에서 열고 return_url로의 navigation을 가로챈 다음, statuspayment_id query parameter를 읽으세요. 위 SDK는 플랫폼의 실제 browser surface에서 이 작업을 대신 처리하므로 Apple Pay와 Google Pay가 계속 작동합니다.

모범 사례

  • Security: 앱에 API key를 절대 포함하지 마세요. backend에서 checkout session을 생성하고 결과로 얻은 checkout_url만 client에 전달하세요.
  • Authority: CheckoutResult.status를 UI hint로 취급하세요. backend에서 payment를 확인한 후에만 access를 허용하세요.
  • User Experience: backend가 session을 생성하는 동안 loading state를 표시하고, cancelled를 error가 아닌 정상적인 결과로 처리하세요.
  • Testing: test mode와 test card를 사용하고, simulator뿐 아니라 실제 device에서도 return-URL round trip을 확인하세요.

문제 해결

일반적인 문제

  • Callback이 도착하지 않음: returnUrl의 scheme은 등록한 scheme과 일치해야 합니다. Android에서는 dodoCallbackScheme manifest placeholder이고, iOS와 React Native에서는 Info.plist URL type입니다.
  • Checkout이 앱 대신 browser로 돌아감(iOS): 수신 URL을 전달하지 않았습니다. .onOpenURL, scene(_:openURLContexts:) 또는 React Native Linking listener에서 DodoCheckout.handleOpenURL(url)를 호출하세요.
  • Android에서 PLATFORM_ERROR: 대부분 scheme 불일치가 원인입니다. MainActivityandroid:taskAffinity=""를 설정한 경우에도 발생할 수 있습니다. 이는 기본 flutter create 설정이며, 일부 OEM build에서 진행 중인 checkout을 잃게 할 수 있습니다.
  • ALREADY_IN_PROGRESS: checkout이 아직 열려 있습니다. 새 checkout을 시작하기 전에 이전 checkout이 완료되거나 닫힐 때까지 기다리세요.
  • 해결되지 않은 placeholder로 인해 build 실패: Android SDK를 추가했지만 manifestPlaceholders["dodoCallbackScheme"]를 설정하지 않았습니다.
  • Payment는 성공했지만 access가 허용되지 않음: 모바일 결과에 의존하는 경우 예상되는 동작입니다. 대신 payment.succeeded / subscription.active webhook을 통해 access를 허용하세요.

추가 리소스

질문이나 지원이 필요하면 support@dodopayments.com으로 문의하세요.
마지막 수정일 2026년 7월 31일