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。

错误

start 仅会在误用或平台故障时抛出 CheckoutException。付款已取消或被拒绝时始终返回结果，而不是抛出异常。

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

已放弃的会话

如果应用在结账过程中被终止，请在下次启动时恢复该 session，并与 backend 进行对账。

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 package。

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

安装

使用

结果含义

验证付款

错误

已放弃的会话

相关内容