Flutter

이는 pub.dev의 공식 Dodo Payments Flutter 패키지입니다 (dodopayments_checkout ). 별도로 커뮤니티에서 제작한 패키지도 제공됩니다. 자세한 내용은 Community Projects를 참조하세요.

Checkout Sessions API

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

Mobile Integration Guide

전체 모바일 결제 흐름에서 이것이 어떻게 사용되는지 확인하세요.

dodopayments_checkout는 iOS에서 Dodo의 호스팅 체크아웃을 SFSafariViewController로, Android에서는 Chrome Custom Tab으로 엽니다 — 독립 실행형 iOS 및 Android SDK에서 사용하는 것과 동일한 네이티브 코어입니다. 모든 체크아웃 로직은 이러한 네이티브 코어에 있으며, Dart 레이어는 타입이 지정된 Pigeon 채널을 통해 호출을 전달합니다. API key를 보유하지 않으며 Dodo Payments API를 직접 호출하지도 않습니다. Flutter 3.44+ / Dart 3.12+, iOS 16+, Android minSdk 23이 필요합니다.

설치

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

ios/Runner/Info.plist에 스킴의 URL type을 추가합니다:

ios/Runner/Info.plist

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

그런 다음 수신 URL을 (예: app_links을 통해) SDK로 전달하세요. SFSafariViewController는 자체 return URL을 가로챌 수 없기 때문입니다:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

여기서는 모든 URL을 전달해도 안전합니다. handleOpenURL는 등록된 returnUrl와 일치하는 URL에만 작동하며, 그 외의 모든 경우에는 false를 반환합니다.

콜백 스킴을 Gradle manifest placeholder로 설정합니다:

android/app/build.gradle

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

MainActivity가 android:taskAffinity=""(기본 flutter create 설정)으로 설정되어 있다면 제거하거나 SDK의 activity에 동일한 affinity를 지정하세요. 그렇지 않으면 일부 OEM Android 빌드에서 진행 중인 체크아웃이 손실되고 PLATFORM_ERROR가 반환될 수 있습니다.

사용법

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

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

결과의 의미

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

CheckoutStatus

필수

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

String?

return URL에 해당 값이 포함되어 있을 때 설정됩니다. UI에 표시하되 액세스 권한을 부여하는 데 사용하지 마세요. 아래의 Verify the Payment를 참조하세요.

String?

subscription 체크아웃에 대해 설정됩니다.

List<String>?

체크아웃에 license key 제품이 포함될 때 설정됩니다.

String?

체크아웃에서 이메일을 수집할 때 설정됩니다.

Map<String, String>

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

결제 확인

Webhooks

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

Get Payment Detail

secret key로 paymentId를 조회하여 상태를 직접 확인하세요.

이 중 하나가 결제를 확인한 후에만 액세스 권한을 부여하세요. result.status만으로 권한을 부여해서는 안 됩니다.

외관 사용자 지정

customization을 통해 CheckoutParams에서 checkout 브라우저의 toolbar, 버튼 및 색 구성표를 사용자 지정할 수 있습니다. 옵션은 플랫폼별로 그룹화되어 있습니다. Android의 Custom Tab과 iOS의 SFSafariViewController은 서로 다른 네이티브 컨트롤을 제공하기 때문입니다. 모든 필드는 선택 사항입니다. customization을 생략하면 각 플랫폼의 기본 외관이 사용됩니다.

Android — Custom Tab

toolbar 배경 색상입니다.

navigation bar 색상입니다.

navigation bar 위에 표시되는 구분선 색상입니다.

CloseButtonStyle

standard은 시스템의 “X” 아이콘을 표시하고, back은 대신 뒤로 가기 화살표를 그립니다.

CloseButtonPosition

toolbar의 어느 쪽에 닫기 버튼이 표시되는지 지정합니다.

toolbar의 공유 아이콘을 표시합니다.

bool

toolbar에서 URL 아래에 페이지 제목을 표시합니다.

bool

페이지를 스크롤할 때 toolbar를 자동으로 숨깁니다.

bool

오버플로 메뉴에 “이 페이지 북마크”를 표시합니다.

bool

오버플로 메뉴에 “페이지 다운로드”를 표시합니다.

BrowserColorScheme

기기의 시스템 설정과 관계없이 밝은 모드 또는 어두운 모드를 강제합니다.

iOS — SFSafariViewController

DismissButtonStyle

닫기 버튼의 레이블 또는 아이콘입니다.

PresentationStyle

pageSheet은 스와이프하여 닫을 수 있는 카드로 표시되고, fullScreen은 전체 화면을 덮습니다.

bool

스크롤할 때 toolbar를 축소할 수 있습니다. presentationStyle이 fullScreen인 경우에만 표시됩니다. pageSheet은 이 설정과 관계없이 bar를 고정된 상태로 유지합니다.

BrowserColorScheme

기기의 시스템 설정과 관계없이 밝은 모드 또는 어두운 모드를 강제합니다.

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

오류

start은 잘못된 사용이나 플랫폼 오류가 발생한 경우에만 CheckoutException을 throw합니다. 취소되거나 거부된 결제는 항상 예외가 아닌 결과로 반환됩니다.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): 유효한 checkout.dodopayments.com session URL이 아닙니다.
invalidReturnUrl (INVALID_RETURN_URL): 유효한 absolute URL이 아닙니다.
alreadyInProgress (ALREADY_IN_PROGRESS): checkout이 이미 실행 중입니다.
platformError (PLATFORM_ERROR): 예기치 않은 플랫폼 오류입니다.

중단된 세션

checkout 도중 앱이 종료된 경우 다음 실행 시 세션을 복구하고 backend와 대조하여 상태를 동기화합니다.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

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

Mobile Integration Guide

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

Community Projects

커뮤니티에서 별도로 개발한 Flutter package도 있습니다.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

설치

사용법

결과의 의미

결제 확인

Webhooks

Get Payment Detail

외관 사용자 지정

오류

중단된 세션

관련 문서

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​설치

​사용법

​결과의 의미

​결제 확인

Webhooks

Get Payment Detail

​외관 사용자 지정

​오류

​중단된 세션

​관련 문서

Mobile Integration Guide

Community Projects

설치

사용법

결과의 의미

결제 확인

외관 사용자 지정

오류

중단된 세션

관련 문서