Skip to main content
이 페이지에서는 공식 Dodo Payments React Native checkout SDK인 @dodopayments/react-native-checkout을 다룹니다. 이 SDK는 Dodo Payments hosted checkout을 네이티브 브라우저 뷰에서 열고 typed result를 반환합니다. 이전 패키지인 dodopayments-react-native-sdk(비스코프)는 API가 다릅니다. 이 페이지에서는 스코프가 지정된 패키지만 설명합니다.

Checkout Sessions API

이 SDK가 여는 checkout_url을 백엔드에서 생성합니다.

Mobile Integration Guide

이 SDK가 전체 모바일 결제 흐름에서 어떻게 사용되는지 확인합니다.
React Native SDK는 네이티브 iOS 및 Android checkout SDK를 래핑하는 Turbo Module입니다. iOS에서는 SFSafariViewController를, Android에서는 Custom Tab을 엽니다. API key를 보유하지 않으며 자체 checkout 로직도 없으므로 Dodo Payments API를 호출하지 않습니다. Checkout은 브라우저 뷰에서 실행됩니다. SDK는 해당 뷰를 표시하고 닫으며 return URL에서 result를 읽습니다.
이 SDK는 New Architecture만 지원합니다. React Native 0.77 이상, iOS 16 이상, Android minSdk 24 이상이 필요합니다. Android 앱은 compileSdk 34 이상으로 빌드해야 합니다.

설치

1

Install the Package

패키지는 자동으로 autolink되며 Maven Central에서 com.dodopayments.api:checkout-android을 가져옵니다.
네이티브 dependency가 자동으로 resolve되므로 다른 설치 단계는 필요하지 않습니다.
Appearance customization에는 version 1.2.0 이상이 필요합니다.
2

Register a Callback URL Scheme

운영 체제가 checkout의 return URL을 앱으로 다시 라우팅하도록 URL scheme을 등록합니다.
android/app/build.gradle에서 scheme을 manifest placeholder로 설정합니다:
android/app/build.gradle
"myapp"을 앱의 scheme으로 바꿉니다.
모든 플랫폼에서 백엔드가 session을 생성할 때 checkout session의 return_url과 동일한 URL을 설정합니다. SDK는 scheme, host, path를 기준으로 return URL을 일치시킵니다. URL이 실제 페이지를 로드할 필요는 없습니다.

사용법

백엔드에서 받은 checkout_url을 사용해 DodoCheckout.start을 호출합니다:
onEvent은 type이 checkout.opened, checkout.return_received 또는 checkout.closed인 event를 수신합니다. 로깅에만 사용하고 결과를 결정하는 데는 절대 사용하지 마세요.

Return URL 전달

iOS에서는 Linking listener가 return URL을 처리해야 합니다. SFSafariViewController가 자체 return URL을 받을 수 없기 때문입니다. Android에서는 handleOpenURL가 아무 작업도 하지 않고 false을 resolve합니다. Android SDK가 redirect를 네이티브로 처리하기 때문입니다. 두 플랫폼 모두에 listener를 등록할 수 있습니다.
iOS에서 handleOpenURL는 URL이 진행 중인 checkout에 속하면 true을 resolve하고, 그 외 URL에는 false을 resolve합니다.

Result의 의미

SDK는 return URL의 query parameters에서 result를 생성합니다.
result.status은 UI hint일 뿐 결제 증명이 아닙니다. payment.succeeded 또는 subscription.active webhook을 사용해 백엔드에서 모든 결제를 확인합니다.
CheckoutStatus
필수
다섯 가지 값 중 하나입니다:
  • succeeded: return URL에 status=succeeded(일회성 결제) 또는 status=active(subscription)이 있습니다.
  • failed: 결제가 거부되었습니다(status=failed).
  • cancelled: return URL이 도착하기 전에 고객이 브라우저 뷰를 닫았습니다. SDK는 결과를 알 수 없으며 결제가 성공했을 수도 있으므로 failure screen을 표시하지 마세요. 대신 abandoned session을 reconcile합니다.
  • pending: 결제가 나중에 정산됩니다(status=processing 또는 모든 requires_* 값). 또는 status parameter가 없거나 인식되지 않았습니다. cancelled과 같은 방식으로 reconcile합니다.
  • expired: checkout session이 만료되었습니다(status=expired).
string
return URL에 포함된 경우 payment_id query parameter입니다. UI에 표시할 수 있지만 access를 부여하는 데 사용하지 마세요. Verify the Payment을 참조하세요.
string
subscription_id query parameter입니다. subscription checkout에 설정됩니다.
string[]
license_key query parameter입니다. checkout에 license key product가 포함될 때 설정됩니다.
string
email query parameter입니다. checkout에서 email address를 수집할 때 설정됩니다.
Record<string, string>
return URL의 모든 query parameter를 있는 그대로 포함합니다.

결제 확인

Webhooks

결제가 성공하거나 subscription이 활성화되면 Dodo Payments가 백엔드를 호출합니다.

Get Payment Detail

secret key를 사용해 paymentId을 조회하여 status를 확인합니다.
이 중 하나가 결제를 확인한 후에만 access를 부여합니다. result.status만 신뢰하지 마세요.

Appearance Customization

checkout browser의 toolbar, button 및 color scheme을 변경하려면 customization을 start(...)에 전달합니다. Android Custom Tabs와 iOS SFSafariViewController는 서로 다른 native control을 노출하므로 option은 android object와 ios object로 그룹화됩니다. 각 플랫폼은 자체 object만 읽습니다. 모든 field는 optional입니다. field를 생략하면 플랫폼이 자체 default를 적용합니다.
string
Toolbar background color를 hex string으로 지정합니다: "#RRGGBB" 또는 "#AARRGGBB".
string
Navigation bar color를 hex string으로 지정합니다.
string
Navigation bar 위 divider의 color를 hex string으로 지정합니다.
'default' | 'back'
default은 system의 “X” icon을 표시합니다. back은 SDK가 그리는 back arrow를 표시합니다.
'start' | 'end'
close button이 표시되는 toolbar의 측면입니다.
boolean
Toolbar의 share icon을 표시합니다. false는 이를 숨깁니다.
boolean
Toolbar에서 URL 아래에 page title을 표시합니다.
boolean
페이지를 스크롤할 때 toolbar를 자동으로 숨깁니다.
boolean
overflow menu에 “Bookmark this page”를 표시합니다.
boolean
overflow menu에 “Download page”를 표시합니다.
'system' | 'light' | 'dark'
light 또는 dark은 device의 system setting과 관계없이 해당 appearance를 강제합니다. system은 system setting을 따릅니다.
'done' | 'close' | 'cancel'
Dismiss button의 style입니다. iOS가 label로 렌더링할지 icon으로 렌더링할지 결정합니다.
'pageSheet' | 'fullScreen'
pageSheet(default)은 고객이 아래로 swipe하여 닫을 수 있는 card를 표시합니다. fullScreen은 전체 화면을 덮습니다.
boolean
페이지를 스크롤할 때 toolbar를 collapse할 수 있습니다. presentationStyle이 fullScreen일 때만 표시되는 효과가 있습니다. pageSheet에서는 이 설정과 관계없이 bar가 고정됩니다.
'system' | 'light' | 'dark'
light 또는 dark은 device의 system setting과 관계없이 해당 appearance를 강제합니다. system은 system setting을 따릅니다.
iOS에는 toolbar color option이 없습니다. 기본이 되는 SFSafariViewController tint property가 iOS 26부터 deprecated되었기 때문입니다.

Errors

start은 misuse 또는 platform failure가 발생한 경우에만 CheckoutError로 reject됩니다. 이유는 error.code에서 읽습니다. 고객의 취소 또는 결제 거부는 항상 result이며 rejection이 아닙니다.
  • INVALID_CHECKOUT_URL: checkoutUrl이 checkout.dodopayments.com 또는 test.checkout.dodopayments.com에서 /session/으로 시작하는 path를 가진 https checkout session URL이 아닙니다.
  • INVALID_RETURN_URL: returnUrl이 scheme과 host를 포함한 absolute URL이 아닙니다.
  • ALREADY_IN_PROGRESS: 다른 checkout이 실행 중입니다. 한 번에 하나의 checkout만 실행할 수 있습니다.
  • PLATFORM_ERROR: 예기치 않은 platform failure입니다. SDK는 인식되지 않은 모든 native error도 이 code로 보고합니다.

Abandoned Sessions

native SDK는 checkout이 시작될 때 checkout session을 기록하고, checkout이 succeeded, failed 또는 expired으로 종료될 때만 record를 삭제합니다. checkout 중 앱 또는 JavaScript bundle이 종료되어 start promise가 손실된 경우와 cancelled 또는 pending result 이후에는 record가 유지됩니다. 다음 mount 시와 cancelled 또는 pending result가 발생할 때마다 확인합니다:
abandoned.sessionId은 cks_으로 시작하는 checkout session ID입니다. abandoned.createdAt은 checkout이 시작된 Date입니다. 백엔드에서 Get Checkout Session을 사용해 session을 조회할 수 있으며, 이 API는 payment_id과 payment_status을 반환합니다. 결제가 최종 status에 도달할 때까지 failed가 아닌 pending으로 처리합니다.

Mobile Integration Guide

Android, iOS 및 Flutter에 동일한 contract를 적용합니다.

Expo Boilerplate

checkout integration이 포함된 완전한 Expo 예제입니다.
마지막 수정일 2026년 9월 26일