Quick Start
Thiết lập tích hợp thanh toán di động của bạn trong 4 bước đơn giản
Platform Examples
Các ví dụ mã hoàn chỉnh cho Android, iOS, React Native và Flutter
Dodo Payments cung cấp SDK checkout chính thức cho Android, iOS, React Native,
và Flutter. Mỗi SDK đóng gói mẫu được tài liệu hóa bên dưới (mở URL checkout,
thu thập kết quả trả về, phân tích kết quả) sau một lệnh gọi
start(...)
được định kiểu duy nhất, đồng thời tích hợp sẵn khả năng khôi phục phiên bị bỏ dở. Chỉ sử dụng WebView thủ công
nếu không SDK nào phù hợp với ngăn xếp công nghệ của bạn.Điều kiện tiên quyết
Trước khi tích hợp Dodo Payments vào ứng dụng di động, hãy đảm bảo bạn có:- Tài khoản Dodo Payments: Tài khoản merchant đang hoạt động với quyền truy cập API
- Thông tin xác thực API: API key và webhook secret key từ dashboard của bạn
- Dự án ứng dụng di động: Ứng dụng Android, iOS, React Native hoặc Flutter
- Backend Server: Để xử lý việc tạo phiên checkout một cách an toàn
Quy trình tích hợp
Tích hợp di động tuân theo quy trình bảo mật gồm 4 bước, trong đó backend của bạn xử lý các lệnh gọi API còn ứng dụng di động quản lý trải nghiệm người dùng.1
Backend: Create Checkout Session
Checkout Session API Docs
Tìm hiểu cách tạo phiên checkout trong backend bằng Node.js, Python và nhiều ngôn ngữ khác. Xem các ví dụ hoàn chỉnh và tài liệu tham chiếu tham số trong tài liệu Checkout Sessions API chuyên dụng.
Bảo mật: Phiên checkout phải được tạo trên backend server, không bao giờ tạo trong ứng dụng di động. Điều này bảo vệ API key của bạn và đảm bảo việc xác thực phù hợp.
2
Mobile: Get Checkout URL
Ứng dụng di động của bạn gọi backend để nhận URL checkout. Xác thực
request này bằng session token của chính người dùng đã đăng nhập.
- iOS (Swift)
- Android (Kotlin)
- React Native (JavaScript)
- Flutter (Dart)
Bảo mật: Ứng dụng di động chỉ giao tiếp với backend của bạn, không bao giờ trực tiếp với Dodo Payments API.
3
Mobile: Open Checkout in Browser
Mở URL checkout trong trình duyệt tích hợp an toàn để xử lý thanh toán.
Hoặc bỏ qua hoàn toàn việc thiết lập thủ công bằng SDK checkout chính thức dành cho
nền tảng của bạn.
Pick your mobile SDK
Các bước cài đặt và hướng dẫn thiết lập cho Android, iOS, React Native và Flutter.
4
Backend: Handle Payment Completion
Xử lý việc hoàn tất thanh toán thông qua webhook và URL redirect để xác nhận trạng thái thanh toán.
Chọn SDK của bạn
Mọi SDK di động đều cung cấp cùng một contract: một lệnh gọistart(...) sẽ mở checkout được lưu trữ của Dodo trong
bề mặt trình duyệt gốc của nền tảng và trả về một CheckoutResult được định kiểu,
trong đó status là succeeded, failed, cancelled,
pending hoặc expired. Không SDK nào lưu API key hoặc gọi Dodo
Payments API, và cả bốn SDK đều hỗ trợ khôi phục phiên bị bỏ dở.
Android
com.dodopayments.api:checkout-android mở Chrome Custom Tab. Yêu cầu minSdk 23.iOS
dodopayments-mobile-sdk-ios mở SFSafariViewController. Yêu cầu iOS 16+.React Native
@dodopayments/react-native-checkout, một Turbo Module trên cả hai native core. Yêu cầu React Native 0.76+.Flutter
dodopayments_checkout, một Pigeon channel trên cả hai native core. Yêu cầu Flutter 3.44+.Đăng ký Callback URL Scheme
Cả bốn SDK đều chuyển quyền điều khiển trở lại ứng dụng của bạn thông qua custom URL scheme do bạn chọn, ví dụmyapp://checkout/return. Đăng ký scheme này một lần cho
mỗi nền tảng:
- Android
- iOS
- Expo
android/app/build.gradle
Bạn muốn tự xây dựng? Mở
checkout_url trong WebView và chặn
việc điều hướng đến return_url, sau đó đọc các tham số query status và payment_id.
Các SDK ở trên thực hiện việc này cho bạn trong bề mặt trình duyệt thực của nền tảng,
đó là lý do Apple Pay và Google Pay vẫn hoạt động.Thực tiễn tốt nhất
- Bảo mật: Không bao giờ đưa API key vào ứng dụng. Tạo phiên checkout trên backend và chỉ truyền
checkout_urlkết quả cho client. - Nguồn xác thực: Xem
CheckoutResult.statuslà gợi ý UI. Chỉ cấp quyền sau khi backend xác nhận thanh toán. - Trải nghiệm người dùng: Hiển thị trạng thái loading trong khi backend tạo phiên và xử lý
cancellednhư một kết quả bình thường thay vì lỗi. - Kiểm thử: Sử dụng test mode và test cards, đồng thời xác minh vòng lặp return-URL trên cả thiết bị thực và simulator.
Khắc phục sự cố
Các vấn đề thường gặp
- Callback không bao giờ đến: Scheme trong
returnUrlphải khớp với scheme bạn đã đăng ký. Trên Android, đó là manifest placeholderdodoCallbackScheme; trên iOS và React Native, đó là URL typeInfo.plist. - Checkout quay lại trình duyệt thay vì ứng dụng của bạn (iOS): Bạn chưa chuyển tiếp URL đến. Gọi
DodoCheckout.handleOpenURL(url)từ.onOpenURL,scene(_:openURLContexts:)hoặc listenerLinkingcủa React Native. PLATFORM_ERRORtrên Android: Thường là do scheme không khớp. Lỗi này cũng có thể xuất hiện nếuMainActivitycủa bạn đặtandroid:taskAffinity=""(giá trị mặc địnhflutter createcó sẵn), khiến một số bản build OEM làm mất checkout đang thực hiện.ALREADY_IN_PROGRESS: Một checkout vẫn đang mở. Hãy chờ hoặc đóng checkout trước đó trước khi bắt đầu một checkout khác.- Build thất bại với placeholder chưa được phân giải: Bạn đã thêm Android SDK nhưng chưa đặt
manifestPlaceholders["dodoCallbackScheme"]. - Thanh toán thành công nhưng quyền truy cập chưa được cấp: Đây là điều dự kiến nếu bạn dựa trên kết quả từ thiết bị di động. Thay vào đó, hãy cấp quyền từ webhook
payment.succeeded/subscription.active.
Tài nguyên bổ sung
Nếu có câu hỏi hoặc cần hỗ trợ, hãy liên hệ support@dodopayments.com.