Skip to main content

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.
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ọi start(...) 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 đó statussucceeded, 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+.
status bạn nhận được chỉ là gợi ý UI, không phải bằng chứng thanh toán. Xác nhận mọi thanh toán từ backend của bạn thông qua webhook payment.succeeded / subscription.active, hoặc truy xuất khoản thanh toán bằng secret key của bạn.

Đă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/app/build.gradle
Manifest của chính SDK đã khai báo redirect activity, vì vậy bạn không cần thêm manifest XML.
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 statuspayment_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_url kết quả cho client.
  • Nguồn xác thực: Xem CheckoutResult.status là 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ý cancelled như 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 returnUrl phải khớp với scheme bạn đã đăng ký. Trên Android, đó là manifest placeholder dodoCallbackScheme; trên iOS và React Native, đó là URL type Info.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 listener Linking của React Native.
  • PLATFORM_ERROR trên Android: Thường là do scheme không khớp. Lỗi này cũng có thể xuất hiện nếu MainActivity của bạn đặt android:taskAffinity="" (giá trị mặc định flutter create có 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.
Lần sửa đổi cuối 31 tháng 7, 2026