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.

Lỗi

start chỉ throw CheckoutException khi sử dụng sai hoặc nền tảng gặp lỗi. Thanh toán bị hủy hoặc bị từ chối luôn được trả về dưới dạng kết quả, không phải exception.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): không phải session URL của 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 muốn.

Session bị bỏ dở

Nếu ứng dụng bị đóng giữa checkout, hãy khôi phục session trong lần khởi chạy tiếp theo và đối soát session đó 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

Lỗi

Session 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

​Lỗi

​Session 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

Lỗi

Session bị bỏ dở

Liên quan