Trang này trình bày package Flutter chính thức của Dodo Payments,
dodopayments_checkout trên pub.dev. Ngoài ra còn có một package do cộng đồng xây dựng. Xem
Dự án cộng đồng.Checkout Sessions API
Tạo
checkout_url mà SDK này sẽ mở từ backend của bạn.Mobile Integration Guide
Tìm hiểu cách SDK này tích hợp vào toàn bộ quy trình thanh toán trên mobile.
dodopayments_checkout mở hosted checkout của Dodo Payments trong SFSafariViewController trên iOS và trong Custom Tab trên Android, đồng thời trả về CheckoutResult có kiểu dữ liệu. Nó sử dụng cùng native code với các SDK iOS và
Android độc lập, và toàn bộ logic checkout nằm trong native code đó. Lớp Dart truyền mỗi lần gọi qua channel Pigeon có kiểu dữ liệu. Package không chứa API key và không bao giờ gọi Dodo Payments API.
Yêu cầu: Flutter 3.44 trở lên với Dart 3.12 trở lên, iOS 16 trở lên và Android minSdk 23.
Cài đặt
1
Add the Dependency
Thêm package vào Tùy chỉnh giao diện yêu cầu phiên bản 1.1.0 trở lên.Plugin Android biên dịch dựa trên Android SDK 35 theo mặc định. Nếu plugin khác yêu cầu
pubspec.yaml:pubspec.yaml
compileSdk cao hơn, hãy đặt dodoCompileSdk trong gradle.properties của ứng dụng.2
Register a Callback URL Scheme
Đăng ký một URL scheme để hệ điều hành định tuyến URL quay lại của checkout về ứng dụng. Sử dụng scheme này trong
returnUrl bạn truyền cho SDK, và đặt cùng URL đó làm return_url của checkout session khi backend tạo session. URL không cần tải một trang thực tế.- iOS
- Android
Thêm một URL type cho scheme của bạn trong
ios/Runner/Info.plist:ios/Runner/Info.plist
SFSafariViewController không thể tự bắt URL quay lại của mình, vì vậy iOS sẽ mở URL trong ứng dụng của bạn. Chuyển tiếp mọi URL đến SDK, chẳng hạn từ
app_links:Bạn có thể chuyển tiếp mọi URL.
handleOpenURL chỉ xử lý URL khớp với returnUrl của checkout đang diễn ra và resolve true cho URL đó. Với mọi URL khác, nó resolve false. Trên Android, nó luôn resolve false.Cách sử dụng
GọiDodoCheckout.instance.start với checkout_url từ backend của bạn:
onEvent nhận các event có type là CheckoutEventType.opened, returnReceived hoặc closed. Chỉ sử dụng chúng để logging, không bao giờ dùng để quyết định kết quả.
Ý nghĩa của kết quả
SDK xây dựngCheckoutResult từ các query parameter trên URL quay lại.
CheckoutStatus
bắt buộc
Một trong năm giá trị:
succeeded: URL quay lại cóstatus=succeeded(thanh toán một lần) hoặcstatus=active(subscription).failed: khoản thanh toán bị từ chối (status=failed).cancelled: khách hàng đã đóng chế độ xem trình duyệt trước khi URL quay lại xuất hiện. SDK không biết kết quả và khoản thanh toán có thể đã thành công, vì vậy không hiển thị màn hình thất bại. Thay vào đó, hãy đối soát abandoned session.pending: khoản thanh toán được hoàn tất sau đó (status=processinghoặc bất kỳ giá trịrequires_*nào), hoặc parameterstatusbị thiếu hoặc không được nhận diện. Đối soát giống nhưcancelled.expired: checkout session đã hết hạn (status=expired).
String?
Query parameter
payment_id, khi URL quay lại có parameter này. Hiển thị parameter trong UI, nhưng không dùng nó để cấp quyền truy cập. Xem Xác minh khoản thanh toán.String?
Query parameter
subscription_id. Được đặt cho các checkout subscription.List<String>?
Query parameter
license_key. Được đặt khi checkout bao gồm các sản phẩm có license key.String?
Query parameter
email. Được đặt khi checkout thu thập địa chỉ email.Map<String, String>
Mọi query parameter từ URL quay lại, giữ nguyên văn.
Xác minh khoản thanh toán
Webhooks
Dodo Payments gọi backend của bạn khi khoản thanh toán thành công hoặc subscription được kích hoạt.
Get Payment Detail
Tra cứu
paymentId bằng secret key của bạn để kiểm tra trạng thái.result.status.
Tùy chỉnh giao diện
Để thay đổi toolbar, button và bảng màu của trình duyệt checkout, truyền mộtBrowserCustomization làm customization trên CheckoutParams. Android Custom Tabs và iOS SFSafariViewController cung cấp các native control khác nhau, vì vậy các tùy chọn được chia thành AndroidBrowserOptions và IosBrowserOptions. Mỗi platform bỏ qua các tùy chọn của platform còn lại. Mọi field đều không bắt buộc và mặc định là null. Với field null, SDK không đặt tùy chọn đó và platform áp dụng mặc định riêng.
Android — Custom Tab
Android — Custom Tab
Color?
Màu nền toolbar.
Màu navigation bar.
Màu của đường phân cách phía trên navigation bar.
CloseButtonStyle?
standard hiển thị biểu tượng “X” của hệ thống. back hiển thị mũi tên quay lại do SDK vẽ.CloseButtonPosition?
Vị trí trên toolbar nơi nút đóng xuất hiện:
start hoặc end.Hiển thị biểu tượng chia sẻ của toolbar.
false ẩn biểu tượng này.bool?
Hiển thị tiêu đề trang bên dưới URL trong toolbar.
bool?
Tự động ẩn toolbar khi trang được cuộn.
bool?
Hiển thị “Bookmark this page” trong menu overflow.
bool?
Hiển thị “Download page” trong menu overflow.
BrowserColorScheme?
light hoặc dark buộc giao diện đó bất kể cài đặt hệ thống của thiết bị. system tuân theo cài đặt hệ thống.iOS — SFSafariViewController
iOS — SFSafariViewController
DismissButtonStyle?
Kiểu của nút dismiss:
done, close hoặc cancel. iOS quyết định hiển thị dưới dạng label hay icon.PresentationStyle?
pageSheet (được dùng khi bạn để null) hiển thị một card mà khách hàng có thể vuốt xuống để dismiss. fullScreen phủ toàn bộ màn hình.bool?
Cho phép toolbar thu gọn khi trang được cuộn. Tùy chọn này chỉ có hiệu lực khi
presentationStyle là fullScreen. Với pageSheet, các thanh luôn được ghim bất kể cài đặt này.BrowserColorScheme?
light hoặc dark buộc giao diện đó bất kể cài đặt hệ thống của thiết bị. system tuân theo cài đặt hệ thống.SFSafariViewController bên dưới đã bị deprecated kể từ iOS 26.
Lỗi
start chỉ throw CheckoutException khi sử dụng sai hoặc platform failure. Đọc lý do từ code, một CheckoutErrorCode. Chuỗi native code nằm trong nativeCode.
Khách hàng hủy hoặc khoản thanh toán bị từ chối luôn là một result, không phải exception.
invalidCheckoutUrl(INVALID_CHECKOUT_URL):checkoutUrlkhông phải là checkout session URLhttps(path bắt đầu bằng/session/) trêncheckout.dodopayments.comhoặctest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlkhông phải URL tuyệt đối có scheme và host.alreadyInProgress(ALREADY_IN_PROGRESS): một checkout khác đang chạy. Mỗi lần chỉ có thể chạy một checkout.platformError(PLATFORM_ERROR): platform failure không mong đợi. Các native error không xác định cũng được ánh xạ đến code này.
Abandoned session
Native SDK ghi lại checkout session khi checkout bắt đầu và chỉ xóa bản ghi khi checkout kết thúc với
succeeded, failed hoặc expired. Bản ghi vẫn còn khi ứng dụng bị tắt trong lúc checkout và sau result cancelled hoặc pending. Kiểm tra bản ghi này ở lần khởi chạy tiếp theo và sau mỗi result cancelled hoặc pending.abandoned.sessionId là ID của checkout session, bắt đầu bằng cks_. abandoned.createdAt là thời điểm DateTime checkout bắt đầu. Backend của bạn có thể tra cứu session bằng Get Checkout Session, trả về payment_id và payment_status. Cho đến khi khoản thanh toán đạt trạng thái cuối cùng, hãy coi khoản thanh toán là đang chờ xử lý, không phải thất bại.
Liên quan
Mobile Integration Guide
Cùng một contract cho Android, iOS và React Native.
Community Projects
Ngoài ra còn có một package Flutter do cộng đồng xây dựng.