Skip to main content

Quick Start

通过四个简单步骤启动移动支付集成

Platform Examples

Android、iOS、React Native 和 Flutter 的完整代码示例
Dodo Payments 为 Android、iOS、React Native 和 Flutter 提供官方结账 SDK。每个 SDK 都将下方记录的模式(打开结账 URL、捕获返回结果、解析结果)封装在一次类型安全的 start(...) 调用中,并内置了已放弃会话的恢复功能。只有在这些 SDK 都不适用于你的技术栈时,才应使用手动 WebView。

前置条件

在将 Dodo Payments 集成到移动应用之前,请确保你具备以下条件:
  • Dodo Payments 账户:已激活且拥有 API 访问权限的商户账户
  • API 凭据:从控制面板获取的 API key 和 webhook secret key
  • 移动应用项目:Android、iOS、React Native 或 Flutter 应用
  • 后端服务器:用于安全地处理结账会话创建

集成流程

移动端集成遵循安全的 4 步流程:后端处理 API 调用,移动应用管理用户体验。
1

Backend: Create Checkout Session

Checkout Session API Docs

了解如何使用 Node.js、Python 等语言在后端创建结账会话。完整示例和参数参考请参阅专门的 Checkout Sessions API 文档。
安全性:结账会话必须在后端服务器上创建,绝不能在移动应用中创建。这样可以保护你的 API keys,并确保正确完成验证。
2

Mobile: Get Checkout URL

移动应用调用你的后端以获取结账 URL。请使用已登录用户自己的会话 token 对此请求进行身份验证。
安全性:移动应用只能与你的后端通信,绝不能直接调用 Dodo Payments API。
3

Mobile: Open Checkout in Browser

在安全的应用内浏览器中打开结账 URL 以处理付款。 或者,使用适用于你平台的官方结账 SDK,完全跳过手动设置。

Pick your mobile SDK

Android、iOS、React Native 和 Flutter 的安装步骤与设置说明。
4

Backend: Handle Payment Completion

通过 webhooks 和重定向 URL 处理付款完成事件,以确认付款状态。

选择你的 SDK

每个移动 SDK 都公开相同的契约:一次 start(...) 调用会在平台的原生浏览器界面中打开 Dodo 托管的结账页面,并返回一个类型化的 CheckoutResult,其 statussucceededfailedcancelledpendingexpired。它们都不会保存 API key 或调用 Dodo Payments API,并且四者都支持已放弃会话的恢复。

Android

com.dodopayments.api:checkout-android 会打开 Chrome Custom Tab。需要 minSdk 23。

iOS

dodopayments-mobile-sdk-ios 会打开 SFSafariViewController。需要 iOS 16+。

React Native

@dodopayments/react-native-checkout 是一个跨两个原生核心的 Turbo Module。需要 React Native 0.76+。

Flutter

dodopayments_checkout 是一个跨两个原生核心的 Pigeon channel。需要 Flutter 3.44+。
你收到的 status 只是 UI 提示,并不能证明付款已完成。请通过 payment.succeeded / subscription.active webhook 从后端确认每笔付款,或使用 secret key 检索付款。

注册回调 URL Scheme

四个 SDK 都会通过你选择的自定义 URL scheme 将控制权交还给应用,例如 myapp://checkout/return。请在每个平台中注册一次:
android/app/build.gradle
SDK 自带的 manifest 已声明重定向 activity,因此无需添加 manifest XML。
想自行构建?在 WebView 中打开 checkout_url 并拦截导航至 return_url,然后读取 statuspayment_id 查询参数。上述 SDK 会在平台的真实浏览器界面中替你完成这些操作,因此 Apple Pay 和 Google Pay 能够继续正常工作。

最佳实践

  • 安全性:绝不要在应用中发布 API key。在后端创建结账会话,并仅将生成的 checkout_url 传递给客户端。
  • 权威性:将 CheckoutResult.status 视为 UI 提示。只有在后端确认付款后,才授予访问权限。
  • 用户体验:后端创建会话时显示加载状态,并将 cancelled 作为正常结果处理,而不是错误。
  • 测试:使用测试模式和测试卡,并在真实设备和模拟器上验证返回 URL 的往返流程。

故障排除

常见问题

  • 始终收不到回调returnUrl 中的 scheme 必须与注册的 scheme 匹配。在 Android 上,这是 dodoCallbackScheme manifest placeholder;在 iOS 和 React Native 上,这是 Info.plist URL type。
  • 结账返回浏览器而不是应用(iOS):你尚未转发传入的 URL。请从 .onOpenURLscene(_:openURLContexts:) 或 React Native Linking listener 调用 DodoCheckout.handleOpenURL(url)
  • Android 上出现 PLATFORM_ERROR:通常是 scheme 不匹配。也可能是因为你的 MainActivity 设置了 android:taskAffinity=""(即标准 flutter create 默认值),导致部分 OEM 构建丢失正在进行中的结账流程。
  • ALREADY_IN_PROGRESS:结账仍处于打开状态。开始新的结账前,请等待或关闭上一个结账。
  • 构建因未解析的 placeholder 失败:你添加了 Android SDK,但从未设置 manifestPlaceholders["dodoCallbackScheme"]
  • 付款已成功但未授予访问权限:如果你依据移动端结果授予权限,这是预期行为。请改为通过 payment.succeeded / subscription.active webhook 授予访问权限。

其他资源

如有疑问或需要支持,请联系 support@dodopayments.com
最后修改于 2026年7月31日