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 对此请求进行身份验证。
- iOS (Swift)
- Android (Kotlin)
- React Native (JavaScript)
- Flutter (Dart)
安全性:移动应用只能与你的后端通信,绝不能直接调用 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,其 status 为 succeeded、failed、cancelled、pending 或 expired。它们都不会保存 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+。注册回调 URL Scheme
四个 SDK 都会通过你选择的自定义 URL scheme 将控制权交还给应用,例如myapp://checkout/return。请在每个平台中注册一次:
- Android
- iOS
- Expo
android/app/build.gradle
想自行构建?在 WebView 中打开
checkout_url 并拦截导航至 return_url,然后读取 status 和 payment_id 查询参数。上述 SDK 会在平台的真实浏览器界面中替你完成这些操作,因此 Apple Pay 和 Google Pay 能够继续正常工作。最佳实践
- 安全性:绝不要在应用中发布 API key。在后端创建结账会话,并仅将生成的
checkout_url传递给客户端。 - 权威性:将
CheckoutResult.status视为 UI 提示。只有在后端确认付款后,才授予访问权限。 - 用户体验:后端创建会话时显示加载状态,并将
cancelled作为正常结果处理,而不是错误。 - 测试:使用测试模式和测试卡,并在真实设备和模拟器上验证返回 URL 的往返流程。
故障排除
常见问题
- 始终收不到回调:
returnUrl中的 scheme 必须与注册的 scheme 匹配。在 Android 上,这是dodoCallbackSchememanifest placeholder;在 iOS 和 React Native 上,这是Info.plistURL type。 - 结账返回浏览器而不是应用(iOS):你尚未转发传入的 URL。请从
.onOpenURL、scene(_:openURLContexts:)或 React NativeLinkinglistener 调用DodoCheckout.handleOpenURL(url)。 - Android 上出现
PLATFORM_ERROR:通常是 scheme 不匹配。也可能是因为你的MainActivity设置了android:taskAffinity=""(即标准flutter create默认值),导致部分 OEM 构建丢失正在进行中的结账流程。 ALREADY_IN_PROGRESS:结账仍处于打开状态。开始新的结账前,请等待或关闭上一个结账。- 构建因未解析的 placeholder 失败:你添加了 Android SDK,但从未设置
manifestPlaceholders["dodoCallbackScheme"]。 - 付款已成功但未授予访问权限:如果你依据移动端结果授予权限,这是预期行为。请改为通过
payment.succeeded/subscription.activewebhook 授予访问权限。
其他资源
如有疑问或需要支持,请联系 support@dodopayments.com。