Flutter

这是官方的 Dodo Payments Flutter package（dodopayments_checkout 在 pub.dev 上）。此外还有一个由社区构建的独立 package，参见社区项目。

Checkout Sessions API

从你的 backend 创建此 SDK 要打开的 checkout_url。

Mobile Integration Guide

了解它如何融入完整的移动支付流程。

dodopayments_checkout 会在 iOS 上的 SFSafariViewController 和 Android 上的 Chrome Custom Tab 中打开 Dodo 的托管结账页面——使用的是与独立的 iOS 和 Android SDK 相同的原生核心。所有结账逻辑都位于这些原生核心中；Dart 层通过类型化的 Pigeon channel 传递调用。它不持有 API key，也不会调用 Dodo Payments API。需要 Flutter 3.44+ / Dart 3.12+、iOS 16+，以及 Android minSdk 23。

安装

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

在 ios/Runner/Info.plist 中添加一个用于 scheme 的 URL type：

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>

然后将收到的 URL（例如通过 app_links）转发到 SDK，因为 SFSafariViewController 无法捕获自己的返回 URL：

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

在这里转发每个 URL 都是安全的。handleOpenURL 只会处理与已注册的 returnUrl 匹配的 URL，并会为其他 URL 解析 false。

将 callback scheme 设置为 Gradle manifest placeholder：

android/app/build.gradle

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

如果 MainActivity 设置了 android:taskAffinity=""（标准的 flutter create 默认值），请移除该设置，或为 SDK 的 activities 设置相同的 affinity。否则，某些 OEM Android 构建可能会丢失进行中的结账流程，并返回 PLATFORM_ERROR。

使用

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();
}

结果含义

result.status 是 UI 提示，而不是付款凭证。请始终通过 payment.succeeded / subscription.active webhook 从 backend 确认每笔付款。

CheckoutStatus

必填

以下值之一：succeeded、failed、cancelled、pending、expired。

String?

当返回 URL 包含该值时设置。将其显示在 UI 中，但不要使用它来授予访问权限。请参见下方的“验证付款”。

String?

用于订阅结账时设置。

List<String>?

当结账包含 license key 产品时设置。

String?

当结账捕获 email 时设置。

Map<String, String>

返回 URL 中的每个 query parameter，均按原样保留。

验证付款

Webhooks

付款成功或订阅激活时，Dodo Payments 会调用你的 backend。

Get Payment Detail

使用你的 secret key 查询 paymentId，直接检查其状态。

只有在以下任一方式确认付款后，才能授予访问权限，绝不能仅依据 result.status。

外观自定义

通过 customization 在 CheckoutParams 上自定义 checkout 浏览器的工具栏、按钮和配色方案。选项按平台分组，因为 Android 的 Custom Tab 和 iOS 的 SFSafariViewController 提供了不同的原生控件。所有字段均为可选；省略 customization 后，将使用各平台的默认外观。

Android — Custom Tab

工具栏背景色。

导航栏颜色。

导航栏上方分隔线的颜色。

CloseButtonStyle

standard 显示系统的“X”图标；back 则显示返回箭头。

CloseButtonPosition

关闭按钮在工具栏哪一侧显示。

显示工具栏的分享图标。

bool

在工具栏中 URL 下方显示页面标题。

bool

页面滚动时允许工具栏自动隐藏。

bool

在溢出菜单中显示“将此页面加入书签”。

bool

在溢出菜单中显示“下载页面”。

BrowserColorScheme

无论设备的系统设置如何，强制使用浅色或深色外观。

iOS — SFSafariViewController

DismissButtonStyle

关闭按钮的标签或图标。

PresentationStyle

pageSheet 显示为可滑动关闭的卡片；fullScreen 覆盖整个屏幕。

bool

允许工具栏在滚动时折叠。仅当 presentationStyle 为 fullScreen 时可见——无论此设置如何，pageSheet 都会使各栏保持固定。

BrowserColorScheme

无论设备的系统设置如何，强制使用浅色或深色外观。

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,
      ),
    ),
  ),
);

错误

start 仅在使用方式错误或平台故障时抛出 CheckoutException。已取消或被拒绝的支付始终会作为结果返回，而不会作为异常抛出。

invalidCheckoutUrl（INVALID_CHECKOUT_URL）：不是 checkout.dodopayments.com session URL。
invalidReturnUrl（INVALID_RETURN_URL）：不是有效的绝对 URL。
alreadyInProgress（ALREADY_IN_PROGRESS）：checkout 已在运行。
platformError（PLATFORM_ERROR）：意外的平台故障。

已放弃的会话

如果应用在 checkout 过程中被终止，请在下次启动时恢复会话，并将其与后端进行协调。

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();
}

Mobile Integration Guide

Android、iOS 和 React Native 使用相同的契约。

Community Projects

此外还有一个由社区构建的独立 Flutter 软件包。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

安装

使用

结果含义

验证付款

Webhooks

Get Payment Detail

外观自定义

错误

已放弃的会话

相关内容

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​安装

​使用

​结果含义

​验证付款

Webhooks

Get Payment Detail

​外观自定义

​错误

​已放弃的会话

​相关内容

Mobile Integration Guide

Community Projects

安装

使用

结果含义

验证付款

外观自定义

错误

已放弃的会话

相关内容