Trang này trình bày SDK checkout React Native chính thức của Dodo Payments,
@dodopayments/react-native-checkout. SDK mở checkout được lưu trữ trên Dodo Payments trong cửa sổ trình duyệt native và trả về kết quả có kiểu dữ liệu. Một package cũ hơn, dodopayments-react-native-sdk (không có scope), có API khác. Trang này chỉ dokument package có scope.Checkout Sessions API
Tạo
checkout_url mà SDK này sẽ mở từ backend của bạn.Mobile Integration Guide
Xem SDK này phù hợp như thế nào trong toàn bộ quy trình thanh toán trên mobile.
SFSafariViewController trên iOS và Custom Tab trên Android. SDK không chứa API key và không có logic checkout riêng, vì vậy không bao giờ gọi Dodo Payments API. Checkout chạy trong cửa sổ trình duyệt. SDK hiển thị và đóng cửa sổ đó, đồng thời đọc kết quả từ return URL.
Cài đặt
1
Install the Package
- Android
- iOS
- Expo
Package được autolink và lấy Dependency native được phân giải tự động, vì vậy không cần thêm bước cài đặt nào khác.
com.dodopayments.api:checkout-android từ Maven Central.2
Register a Callback URL Scheme
Đăng ký một URL scheme để hệ điều hành định tuyến return URL của checkout trở lại ứng dụng của bạn.Trên mọi platform, hãy đặt cùng một URL với
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
Đặt scheme làm manifest placeholder trong Thay
android/app/build.gradle:android/app/build.gradle
"myapp" bằng scheme của ứng dụng.return_url của checkout session khi backend tạo session. SDK đối chiếu return URL theo scheme, host và path. URL không cần tải một trang thực tế.Cách sử dụng
GọiDodoCheckout.start với checkout_url từ backend của bạn:
onEvent nhận các event có type là checkout.opened, checkout.return_received hoặc checkout.closed. Chỉ sử dụng chúng để logging, không bao giờ dùng để quyết định kết quả.
Chuyển tiếp Return URL
iOS cần listenerLinking để xử lý return URL, vì SFSafariViewController không thể tự bắt return URL của nó. Trên Android, handleOpenURL không làm gì và resolve false, vì Android SDK bắt redirect ở native. Bạn có thể đăng ký listener trên cả hai platform.
handleOpenURL resolve true khi URL thuộc về checkout đang thực hiện và false đối với mọi URL khác.
Ý nghĩa của kết quả
SDK xây dựng kết quả từ các query parameter trên return URL.CheckoutStatus
bắt buộc
Một trong năm giá trị:
succeeded: return URL 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: customer đã đóng cửa sổ trình duyệt trước khi return URL đế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 settlement 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. Hãy đối soát như vớicancelled.expired: checkout session đã hết hạn (status=expired).
string
Query parameter
payment_id, khi return URL có chứa 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 thiết lập cho subscription checkout.string[]
Query parameter
license_key. Được thiết lập khi checkout bao gồm các sản phẩm có license key.string
Query parameter
email. Được thiết lập khi checkout thu thập địa chỉ email.Record<string, string>
Mọi query parameter từ return URL, giữ nguyên văn.
Xác minh khoản thanh toán
Webhooks
Dodo Payments gọi backend của bạn khi một khoản thanh toán thành công hoặc một subscription được kích hoạt.
Get Payment Detail
Tra cứu
paymentId bằng secret key để kiểm tra trạng thái.result.status.
Tùy chỉnh giao diện
Để thay đổi toolbar, button và color scheme của trình duyệt checkout, truyềncustomization vào start(...). Android Custom Tabs và SFSafariViewController trên iOS cung cấp các native control khác nhau, vì vậy các tùy chọn được nhóm thành object android và object ios. Mỗi platform chỉ đọc object của chính nó. Mọi field đều là tùy chọn. Khi bạn bỏ qua một field, platform sẽ áp dụng giá trị mặc định riêng.
Android — Custom Tab
Android — Custom Tab
string
Màu nền toolbar, dưới dạng chuỗi hex:
"#RRGGBB" hoặc "#AARRGGBB".Màu navigation bar, dưới dạng chuỗi hex.
Màu của đường phân cách phía trên navigation bar, dưới dạng chuỗi hex.
'default' | 'back'
default hiển thị icon “X” của hệ thống. back hiển thị mũi tên quay lại do SDK vẽ.'start' | 'end'
Mặt của toolbar nơi close button xuất hiện.
Hiển thị share icon của toolbar.
false ẩn icon này.boolean
Hiển thị tiêu đề trang bên dưới URL trong toolbar.
boolean
Tự động ẩn toolbar khi trang được cuộn.
boolean
Hiển thị “Bookmark this page” trong menu overflow.
boolean
Hiển thị “Download page” trong menu overflow.
'system' | 'light' | 'dark'
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
'done' | 'close' | 'cancel'
Kiểu của dismiss button. iOS quyết định hiển thị dưới dạng label hay icon.
'pageSheet' | 'fullScreen'
pageSheet (mặc định) hiển thị một card mà customer có thể vuốt xuống để đóng. fullScreen bao phủ toàn bộ màn hình.boolean
Cho phép toolbar thu gọn khi trang được cuộn. 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.'system' | 'light' | 'dark'
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ỉ reject với CheckoutError khi sử dụng sai hoặc xảy ra lỗi platform. Đọc lý do từ error.code. Customer hủy hoặc khoản thanh toán bị từ chối luôn là một result, không phải rejection.
INVALID_CHECKOUT_URL:checkoutUrlkhông phải là URL checkout sessionhttps(path bắt đầu bằng/session/) trêncheckout.dodopayments.comhoặctest.checkout.dodopayments.com.INVALID_RETURN_URL:returnUrlkhông phải là absolute URL có scheme và host.ALREADY_IN_PROGRESS: một checkout khác đang chạy. Mỗi lần chỉ có thể chạy một checkout.PLATFORM_ERROR: lỗi platform không mong đợi. SDK cũng báo cáo mọi native error không được nhận diện bằng 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ớisucceeded, failed hoặc expired. Bản ghi vẫn tồn tại khi ứng dụng hoặc JavaScript bundle bị kill trong lúc checkout, làm mất promise start, và sau result cancelled hoặc pending. Kiểm tra bản ghi này khi mount 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 Date checkout bắt đầu. Backend của bạn có thể tra cứu session bằng Get Checkout Session, endpoint này 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 xử lý như đang pending, không phải failed.
Liên quan
Mobile Integration Guide
Cùng một contract cho Android, iOS và Flutter.
Expo Boilerplate
Ví dụ Expo hoàn chỉnh với tích hợp checkout.