Skip to main content
이 페이지에서는 pub.dev의 공식 Dodo Payments Flutter package인 dodopayments_checkout를 다룹니다. 별도의 community-built package도 있습니다. Community Projects를 참조하세요.

Checkout Sessions API

이 SDK가 여는 checkout_url를 backend에서 생성하세요.

Mobile Integration Guide

이 SDK가 전체 mobile payment flow에서 어떻게 사용되는지 확인하세요.
dodopayments_checkout는 iOS에서 SFSafariViewController로, Android에서 Custom Tab으로 Dodo Payments hosted checkout을 열고 typed CheckoutResult를 반환합니다. 독립 실행형 iOS 및 Android SDK와 동일한 native code를 사용하며, 모든 checkout logic은 해당 native code에 있습니다. Dart layer는 각 호출을 typed Pigeon channel을 통해 전달합니다. 이 package에는 API key가 포함되지 않으며 Dodo Payments API를 직접 호출하지 않습니다. Requirements: Dart 3.12 이상이 포함된 Flutter 3.44 이상, iOS 16 이상, Android minSdk 23.

설치

1

Add the Dependency

package를 pubspec.yaml에 추가하세요:
pubspec.yaml
Appearance customization에는 version 1.1.0 이상이 필요합니다.Android plugin은 기본적으로 Android SDK 35에 대해 compile됩니다. 다른 plugin에 더 높은 compileSdk가 필요한 경우 앱의 gradle.properties에서 dodoCompileSdk를 설정하세요.
2

Register a Callback URL Scheme

운영 체제가 checkout의 return URL을 앱으로 다시 라우팅하도록 URL scheme을 등록하세요. SDK에 전달하는 returnUrl에서 이 scheme을 사용하고, backend가 session을 생성할 때 checkout session의 return_url에도 동일한 URL을 설정하세요. URL이 실제 페이지를 로드할 필요는 없습니다.
ios/Runner/Info.plist에서 scheme에 대한 URL type을 추가하세요:
ios/Runner/Info.plist
SFSafariViewController는 자체 return URL을 처리할 수 없으므로 iOS가 대신 앱에서 URL을 엽니다. 수신되는 모든 URL을 SDK로 전달하세요. 예를 들어 app_links에서 전달할 수 있습니다:
모든 URL을 전달해도 됩니다. handleOpenURL는 진행 중인 checkout의 returnUrl와 일치하는 URL에만 작동하며, 해당 URL에 대해 true를 resolve합니다. 다른 URL의 경우 false를 resolve합니다. Android에서는 항상 false를 resolve합니다.

사용법

backend의 checkout_url를 사용해 DodoCheckout.instance.start를 호출하세요:
onEvent는 type가 CheckoutEventType.opened, returnReceived 또는 closed인 event를 수신합니다. logging에만 사용하고 결과를 결정하는 데는 절대 사용하지 마세요.

Result의 의미

SDK는 return URL의 query parameters에서 CheckoutResult를 생성합니다.
result.status는 결제 증명이 아닌 UI hint입니다. payment.succeeded 또는 subscription.active webhook을 사용해 backend에서 모든 payment를 확인하세요.
CheckoutStatus
필수
다섯 가지 값 중 하나입니다:
  • succeeded: return URL에 status=succeeded(one-time payment) 또는 status=active(subscription)이 있습니다.
  • failed: payment가 거절되었습니다(status=failed).
  • cancelled: return URL이 도착하기 전에 customer가 browser view를 닫았습니다. SDK는 결과를 알 수 없으며 payment가 성공했을 수도 있으므로 failure screen을 표시하지 마세요. 대신 abandoned session을 reconcile하세요.
  • pending: payment가 나중에 정산됩니다(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에 설정됩니다.
List<String>?
license_key query parameter입니다. checkout에 license key products가 포함된 경우 설정됩니다.
String?
email query parameter입니다. checkout에서 email address를 수집할 때 설정됩니다.
Map<String, String>
return URL의 모든 query parameter를 있는 그대로 포함합니다.

Payment 확인

Webhooks

payment가 성공하거나 subscription이 활성화되면 Dodo Payments가 backend를 호출합니다.

Get Payment Detail

secret key를 사용해 paymentId를 조회하여 status를 확인하세요.
이 중 하나가 payment를 확인한 후에만 access를 부여하세요. result.status만 의존하지 마세요.

Appearance Customization

checkout browser의 toolbar, buttons 및 color scheme을 변경하려면 CheckoutParams에서 customization로 BrowserCustomization를 전달하세요. Android Custom Tabs와 iOS SFSafariViewController는 서로 다른 native controls를 제공하므로 options는 AndroidBrowserOptions와 IosBrowserOptions로 나뉩니다. 각 platform은 다른 platform의 options를 무시합니다. 모든 field는 optional이며 기본값은 null입니다. null field의 경우 SDK가 해당 option을 설정하지 않고 platform 자체의 기본값을 적용합니다.
Color?
Toolbar background color입니다.
Color?
Navigation bar color입니다.
Color?
Navigation bar 위에 표시되는 divider의 color입니다.
CloseButtonStyle?
standard는 system의 “X” icon을 표시합니다. back는 SDK가 그리는 back arrow를 표시합니다.
CloseButtonPosition?
close button이 표시되는 toolbar 측면입니다: start 또는 end.
bool?
toolbar의 share icon을 표시합니다. false는 이를 숨깁니다.
bool?
toolbar에서 URL 아래에 page title을 표시합니다.
bool?
페이지를 scroll할 때 toolbar를 자동으로 숨깁니다.
bool?
overflow menu에 “Bookmark this page”를 표시합니다.
bool?
overflow menu에 “Download page”를 표시합니다.
BrowserColorScheme?
light 또는 dark는 device의 system setting과 관계없이 해당 appearance를 강제합니다. system는 system setting을 따릅니다.
DismissButtonStyle?
dismiss button의 style입니다: done, close 또는 cancel. label 또는 icon으로 렌더링할지는 iOS가 결정합니다.
PresentationStyle?
pageSheet(이 null를 그대로 둘 때 사용)는 customer가 아래로 swipe하여 dismiss할 수 있는 card를 표시합니다. fullScreen는 전체 screen을 덮습니다.
bool?
페이지를 scroll할 때 toolbar를 collapse할 수 있습니다. presentationStyle가 fullScreen인 경우에만 눈에 보이는 효과가 있습니다. pageSheet에서는 이 setting과 관계없이 bars가 고정됩니다.
BrowserColorScheme?
light 또는 dark는 device의 system setting과 관계없이 해당 appearance를 강제합니다. system는 system setting을 따릅니다.
iOS 26부터 underlying SFSafariViewController tint properties가 deprecated되었으므로 toolbar color option이 없습니다.

Errors

start는 misuse 또는 platform failure가 발생한 경우에만 CheckoutException를 throw합니다. code에서 reason을 읽으세요. 이는 CheckoutErrorCode입니다. native code string은 nativeCode에 있습니다. customer가 취소하거나 payment가 거절된 경우에는 항상 result이며 exception이 아닙니다.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): checkoutUrl가 checkout.dodopayments.com 또는 test.checkout.dodopayments.com에서 유효한 https checkout session URL이 아닙니다(path가 /session/로 시작해야 함).
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl가 scheme과 host를 포함하는 absolute URL이 아닙니다.
  • alreadyInProgress (ALREADY_IN_PROGRESS): 다른 checkout이 실행 중입니다. 한 번에 하나의 checkout만 실행할 수 있습니다.
  • platformError (PLATFORM_ERROR): 예기치 않은 platform failure입니다. 알 수 없는 native errors도 이 code로 매핑됩니다.

Abandoned Sessions

native SDK는 checkout이 시작될 때 checkout session을 기록하고, checkout이 succeeded, failed 또는 expired로 종료될 때만 해당 record를 삭제합니다. checkout 중 앱이 종료되거나 cancelled 또는 pending result가 발생한 후에도 record는 유지됩니다. 다음 launch 시와 cancelled 또는 pending result가 발생할 때마다 이를 확인하세요.
abandoned.sessionId는 cks_로 시작하는 checkout session ID입니다. abandoned.createdAt는 checkout이 시작된 DateTime입니다. backend는 Get Checkout Session을 사용해 session을 조회할 수 있으며, 이 API는 payment_id와 payment_status를 반환합니다. payment가 final status에 도달할 때까지 실패가 아닌 pending으로 처리하세요.

Mobile Integration Guide

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

Community Projects

별도의 community-built Flutter package도 있습니다.
마지막 수정일 2026년 9월 26일