React Native

这是官方的 Dodo Payments React Native 结账 SDK，@dodopayments/react-native-checkout。它会在原生浏览器视图中打开 Dodo 的托管结账页面，并返回类型化结果。注意：还有一个名为 dodopayments-react-native-sdk（未使用 scope）的旧版无关 package，其 API 完全不同。本页面仅介绍当前官方的 scoped package。

Checkout Sessions API

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

Mobile Integration Guide

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

React Native SDK 是对相同原生 Swift 和 Kotlin 核心的轻量级 Turbo Module 封装。它会在 iOS 上打开 SFSafariViewController，在 Android 上打开 Chrome Custom Tab，不持有 API key，也不会直接调用 Dodo API。所有结账逻辑都在浏览器中运行；SDK 只负责管理视图生命周期并捕获 return URL。

此 SDK 仅要求使用 New Architecture、React Native 0.76+、iOS 16+ 以及 Android minSdk 24。

安装

Install the Package

Android
iOS
Expo

package 会自动链接，并从 Maven 拉取 com.dodopayments.api:checkout-android。

npm i @dodopayments/react-native-checkout

无需其他设置；原生依赖会自动解析。

npm i @dodopayments/react-native-checkout
cd ios && pod install

Swift 核心包含在 package 中，并通过 CocoaPods 安装。

仅适用于开发构建（不适用于 Expo Go）。

npm i @dodopayments/react-native-checkout

然后配置您的 app.json（请参阅下方的“注册回调 URL Scheme”）。

您的应用必须注册 URL scheme，才能接收结账页面返回的 return URL。

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

在 android/app/build.gradle 中：

android/app/build.gradle

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

将 "myapp" 替换为您应用的 scheme。

在 ios/YourApp/Info.plist 中：

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

你也可以通过 Xcode 的 Info → URL Types UI 添加此项。

该 package 自带的 config plugin 会在两个平台的 prebuild 中注册此 scheme。在 app.json 中为其传入 scheme 选项：

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme 必须与传入 returnUrl 的值匹配（例如 myappcheckout://return），并且必须与 expo.scheme 不同。Expo 已经在 MainActivity 上注册了后者，重复使用它可能会将 checkout 返回路由到错误的 screen。编辑 app.json 后，重新构建 native project：

npx expo prebuild --clean

这仅适用于 development builds，不适用于 Expo Go。如果 android/app/build.gradle 由手动维护，且没有供 plugin 查找的标准 defaultConfig { } block，请改为自行添加 placeholder。请参阅上方的 Android tab。

用法

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}

转发 Return URL

Linking listener 是 iOS 处理 return URL 所必需的。在 Android 上，handleOpenURL 是一个 no-op，它会解析 false，因为 Android core 会原生处理其 redirect。在两个平台上无条件注册该 listener 是安全的。

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

结果含义

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

CheckoutStatus

必填

succeeded、failed、cancelled、pending、expired 中的一个。

string

当 return URL 包含其中一项时设置。将其显示在 UI 中，不要使用它来授予访问权限。请参阅下方的“验证付款”。

string

用于 subscription checkout 时设置。

string[]

checkout 包含 license key products 时设置。

string

checkout 捕获 email 时设置。

Record<string, string>

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

验证付款

Webhooks

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

Get Payment Detail

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

仅当其中一项确认付款后才授予访问权限，绝不要仅依据 result.status。

外观自定义

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

Android — Custom Tab

工具栏背景颜色。

导航栏颜色。

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

'default' | 'back'

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

'start' | 'end'

关闭按钮在工具栏中出现的位置。

显示工具栏的分享图标。

boolean

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

boolean

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

boolean

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

boolean

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

'system' | 'light' | 'dark'

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

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

关闭按钮的标签或图标。

'pageSheet' | 'fullScreen'

pageSheet 以支持滑动关闭的卡片形式呈现；fullScreen 覆盖整个屏幕。

boolean

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

'system' | 'light' | 'dark'

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

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

错误

start 仅在误用或平台故障时以 CheckoutError 拒绝。已取消或被拒绝的支付始终是结果，而不是异常。

INVALID_CHECKOUT_URL：不是 checkout.dodopayments.com 会话 URL。
INVALID_RETURN_URL：不是有效的绝对 URL。
ALREADY_IN_PROGRESS：结账已在运行。
PLATFORM_ERROR：意外的平台故障。

已放弃的会话

如果应用或 JS bundle 在结账过程中被终止，promise 会丢失，但原生层仍会保留会话。在下次挂载时恢复该会话，并将其与后端进行协调。

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}

Mobile Integration Guide

适用于 Android、iOS 和 Flutter 的相同契约。

Expo Boilerplate

包含结账集成的完整 Expo 示例。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

安装

用法

转发 Return URL

结果含义

验证付款

Webhooks

Get Payment Detail

外观自定义

错误

已放弃的会话

相关内容

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​安装

​用法

​转发 Return URL

​结果含义

​验证付款

Webhooks

Get Payment Detail

​外观自定义

​错误

​已放弃的会话

​相关内容

Mobile Integration Guide

Expo Boilerplate

安装

用法

转发 Return URL

结果含义

验证付款

外观自定义

错误

已放弃的会话

相关内容