Flutter

Đây là 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 riê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

Xem cách tích hợp bước này vào toàn bộ luồng thanh toán trên mobile.

dodopayments_checkout mở hosted checkout của Dodo trong SFSafariViewController trên iOS và Chrome Custom Tab trên Android — cùng các native core được sử dụng bởi các SDK độc lập iOS và Android. Toàn bộ logic checkout nằm trong các native core đó; lớp Dart chuyển tiếp lệnh gọi qua một kênh Pigeon có kiểu. Lớp này không chứa API key và không bao giờ gọi Dodo Payments API. Yêu cầu Flutter 3.44+ / Dart 3.12+, iOS 16+ và Android minSdk 23.

Cài đặt

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

Thêm một URL type cho scheme của bạn trong ios/Runner/Info.plist:

ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Sau đó chuyển tiếp các URL đến (ví dụ: thông qua app_links) vào SDK, vì SFSafariViewController không thể tự bắt return URL của chính nó:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

Bạn có thể an toàn chuyển tiếp mọi URL tại đây. handleOpenURL chỉ xử lý các URL khớp với returnUrl đã đăng ký của bạn và resolve false cho mọi URL khác.

Đặt callback scheme làm Gradle manifest placeholder:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

Nếu MainActivity đặt android:taskAffinity="" (giá trị mặc định của flutter create), hãy xóa thiết lập này hoặc cung cấp cho các activity của SDK cùng một affinity. Nếu không, một số bản dựng Android của OEM có thể làm mất checkout đang thực hiện và trả về PLATFORM_ERROR.

Cách sử dụng

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}

Ý nghĩa của kết quả

result.status là gợi ý UI, không phải bằng chứng thanh toán. Xác nhận mọi khoản thanh toán trên backend của bạn, thông qua webhook payment.succeeded / subscription.active.

CheckoutStatus

bắt buộc

Một trong các giá trị succeeded, failed, cancelled, pending, expired.

String?

Được đặt khi return URL chứa giá trị này. Hiển thị giá trị trong UI, không dùng nó để cấp quyền truy cập. Xem phần Xác minh thanh toán bên dưới.

String?

Được đặt cho các checkout đăng ký.

List<String>?

Được đặt khi checkout bao gồm các sản phẩm có license key.

String?

Được đặt khi checkout thu thập email.

Map<String, String>

Mọi query parameter từ return URL, giữ nguyên từng ký tự.

Xác minh 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 của bạn để kiểm tra trực tiếp trạng thái.

Chỉ cấp quyền truy cập sau khi một trong các cơ chế này xác nhận thanh toán, không bao giờ chỉ dựa vào result.status.

Tùy chỉnh giao diện

Tùy chỉnh thanh công cụ, các nút và bảng màu của trình duyệt checkout thông qua customization trên CheckoutParams. Các tùy chọn được nhóm theo nền tảng vì Custom Tab của Android và SFSafariViewController cung cấp các điều khiển native khác nhau. Tất cả các trường đều là tùy chọn; nếu bỏ qua customization thì giao diện mặc định của từng nền tảng sẽ được sử dụng.

Android — Custom Tab

Màu nền của thanh công cụ.

Màu thanh điều hướng.

Màu đường phân cách phía trên thanh điều hướng.

CloseButtonStyle

standard hiển thị biểu tượng hệ thống “X”; back thay vào đó hiển thị mũi tên quay lại.

CloseButtonPosition

Nút đóng xuất hiện ở phía nào của thanh công cụ.

Hiển thị biểu tượng chia sẻ của thanh công cụ.

bool

Hiển thị tiêu đề trang bên dưới URL trong thanh công cụ.

bool

Cho phép thanh công cụ tự động ẩn khi cuộn trang.

bool

Hiển thị “Bookmark this page” trong menu tùy chọn.

bool

Hiển thị “Download page” trong menu tùy chọn.

BrowserColorScheme

Buộc sử dụng giao diện sáng hoặc tối bất kể cài đặt hệ thống của thiết bị.

iOS — SFSafariViewController

DismissButtonStyle

Nhãn hoặc biểu tượng cho nút loại bỏ.

PresentationStyle

pageSheet hiển thị dưới dạng thẻ có thể vuốt để loại bỏ; fullScreen phủ toàn bộ màn hình.

bool

Cho phép thanh công cụ thu gọn khi cuộn. Chỉ hiển thị khi presentationStyle là fullScreen — pageSheet giữ các thanh cố định bất kể cài đặt này.

BrowserColorScheme

Buộc sử dụng giao diện sáng hoặc tối bất kể cài đặt hệ thống của thiết bị.

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

Lỗi

start chỉ ném CheckoutException khi được sử dụng sai hoặc xảy ra lỗi nền tảng. Thanh toán bị hủy hoặc bị từ chối luôn là một result, không phải một exception.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): không phải URL phiên checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): không phải absolute URL hợp lệ.
alreadyInProgress (ALREADY_IN_PROGRESS): một checkout đang chạy.
platformError (PLATFORM_ERROR): lỗi nền tảng không mong đợi.

Phiên bị bỏ dở

Nếu ứng dụng bị dừng giữa chừng khi checkout, hãy khôi phục phiên trong lần khởi chạy tiếp theo và đối soát phiên đó với backend của bạn.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Cài đặt

Cách sử dụng

Ý nghĩa của kết quả

Xác minh thanh toán

Webhooks

Get Payment Detail

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​Cài đặt

​Cách sử dụng

​Ý nghĩa của kết quả

​Xác minh thanh toán

Webhooks

Get Payment Detail

​Tùy chỉnh giao diện

​Lỗi

​Phiên bị bỏ dở

​Liên quan

Mobile Integration Guide

Community Projects

Cài đặt

Cách sử dụng

Ý nghĩa của kết quả

Xác minh thanh toán

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan