React Native

공식 Dodo Payments React Native checkout SDK인 @dodopayments/react-native-checkout입니다. 이 SDK는 네이티브 브라우저 뷰에서 Dodo의 호스팅 checkout을 열고 typed result를 반환합니다. 참고: 이와 관련이 없는 이전 패키지 dodopayments-react-native-sdk (unscoped)가 존재하며, API가 완전히 다릅니다. 이 페이지에서는 현재 공식 scoped package만 설명합니다.

Checkout Sessions API

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

Mobile Integration Guide

전체 모바일 결제 흐름에서 어떻게 연동되는지 확인하세요.

React Native SDK는 동일한 네이티브 Swift 및 Kotlin 코어를 감싸는 얇은 Turbo Module wrapper입니다. iOS에서는 SFSafariViewController를, Android에서는 Chrome Custom Tab을 열며, API key를 보유하지 않고 Dodo API를 직접 호출하지도 않습니다. 모든 checkout 로직은 브라우저에서 실행되며, SDK는 뷰 lifecycle을 관리하고 return URL을 캡처하기만 합니다.

이 SDK는 New Architecture만 지원하며, React Native 0.76+, iOS 16+, Android minSdk 24가 필요합니다.

설치

Install the Package

Android
iOS
Expo

패키지는 autolink되며 Maven에서 com.dodopayments.api:checkout-android를 가져옵니다.

npm i @dodopayments/react-native-checkout

추가 설정은 필요하지 않습니다. 네이티브 dependency가 자동으로 resolve됩니다.

npm i @dodopayments/react-native-checkout
cd ios && pod install

Swift 코어는 패키지에 포함되어 있으며 CocoaPods를 통해 설치됩니다.

Development builds에서만 사용할 수 있으며 Expo Go에서는 사용할 수 없습니다.

npm i @dodopayments/react-native-checkout
npx expo install expo-build-properties

그런 다음 app.json를 설정합니다(아래의 Register a Callback URL Scheme 참조).

앱은 checkout에서 반환되는 return URL을 수신할 수 있도록 URL scheme을 등록해야 합니다.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

android/app/build.gradle에서:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

"myapp"를 앱의 scheme으로 바꿉니다.

ios/YourApp/Info.plist에서:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Xcode의 Info → URL Types UI를 통해 추가할 수도 있습니다.

app.json에서:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "manifestPlaceholders": {
              "dodoCallbackScheme": "myapp"
            }
          }
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [
          {
            "CFBundleURLSchemes": ["myapp"]
          }
        ]
      }
    }
  }
}

패키지에는 @dodopayments/react-native-checkout Expo config plugin도 포함되어 있지만, 현재는 URL scheme과 manifest placeholder를 작성하지 않습니다. 이것만 추가해도 callback scheme은 등록되지 않습니다. 위의 expo-build-properties 및 infoPlist 설정을 사용하세요.

app.json를 수정한 후 네이티브 프로젝트를 다시 빌드합니다:

npx expo prebuild --clean

이는 development builds에서만 작동하며 Expo Go에서는 작동하지 않습니다.

사용법

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}

Return URL 전달

Linking listener는 iOS의 return-URL 처리를 위해 필요합니다. Android에서는 handleOpenURL가 false를 resolve하는 no-op입니다. Android 코어가 redirect를 네이티브로 처리하기 때문입니다. 두 플랫폼 모두에서 listener를 조건 없이 등록해도 안전합니다.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Result의 의미

result.status는 UI hint일 뿐 결제가 완료되었다는 증거가 아닙니다. payment.succeeded / subscription.active webhook을 통해 백엔드에서 모든 결제를 확인하세요.

CheckoutStatus

필수

succeeded, failed, cancelled, pending, expired 중 하나입니다.

string

return URL에 해당 값이 포함된 경우 설정됩니다. UI에 표시하되 access 권한을 부여하는 데 사용하지 마세요. 자세한 내용은 아래의 Verify the Payment를 참조하세요.

string

subscription checkout에 설정됩니다.

string[]

checkout에 license key product가 포함된 경우 설정됩니다.

string

checkout에서 email을 수집하는 경우 설정됩니다.

Record<string, string>

return URL의 모든 query parameter를 원문 그대로 포함합니다.

결제 확인

Webhooks

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

Get Payment Detail

secret key를 사용해 paymentId를 조회하여 상태를 직접 확인합니다.

이 중 하나가 결제를 확인한 후에 access 권한을 부여하세요. result.status만으로는 절대 부여하지 마세요.

Errors

start는 오용 또는 플랫폼 failure가 발생한 경우에만 CheckoutError와 함께 reject됩니다. 취소되거나 거절된 결제는 항상 result로 반환되며 exception이 발생하지 않습니다.

INVALID_CHECKOUT_URL: 유효한 checkout.dodopayments.com session URL이 아닙니다.
INVALID_RETURN_URL: 유효한 absolute URL이 아닙니다.
ALREADY_IN_PROGRESS: checkout이 이미 실행 중입니다.
PLATFORM_ERROR: 예상하지 못한 플랫폼 failure입니다.

Abandoned Sessions

checkout 도중 앱 또는 JS bundle이 종료되면 promise는 유실되지만 네이티브 레이어는 session을 유지합니다. 다음 mount 시 session을 복구하고 백엔드와 reconcile하세요.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}

Mobile Integration Guide

Android, iOS, Flutter에 동일한 contract를 적용하는 방법입니다.

Expo Boilerplate

checkout integration이 포함된 완전한 Expo 예제입니다.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

설치

사용법

Return URL 전달

Result의 의미

결제 확인

Webhooks

Get Payment Detail

Errors

Abandoned Sessions

관련 문서

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​설치

​사용법

​Return URL 전달

​Result의 의미

​결제 확인

Webhooks

Get Payment Detail

​Errors

​Abandoned Sessions

​관련 문서

Mobile Integration Guide

Expo Boilerplate

설치

사용법

Return URL 전달

Result의 의미

결제 확인

Errors

Abandoned Sessions

관련 문서