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
npx expo install expo-build-properties

然后配置您的 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 添加此配置。

在 app.json 中：

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "manifestPlaceholders": {
              "dodoCallbackScheme": "myapp"
            }
          }
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [
          {
            "CFBundleURLSchemes": ["myapp"]
          }
        ]
      }
    }
  }
}

package 还附带一个 @dodopayments/react-native-checkout Expo config plugin，但目前不会写入 URL scheme 或 manifest placeholder。仅添加它不会注册您的 callback scheme —— 请使用上面的 expo-build-properties 和 infoPlist 配置。

编辑 app.json 后，重新构建原生项目：

npx expo prebuild --clean

这仅适用于开发构建，不适用于 Expo Go。

使用

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 核心会原生处理其 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

用于订阅结账时设置。

string[]

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

string

结账捕获 email 时设置。

Record<string, string>

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

验证支付

Webhooks

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

Get Payment Detail

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

只有这些方式之一确认支付后，才授予访问权限，绝不要仅凭 result.status 授予访问权限。

错误

只有在误用或平台故障时，start 才会以 CheckoutError 拒绝。已取消或被拒绝的支付始终作为结果返回，而不是抛出 exception。

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

已放弃的会话

如果应用或 JS bundle 在结账过程中被终止，promise 会丢失，但原生层会保留 session。请在下次 mount 时恢复该 session，并与您的 backend 对账。

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

结果含义

验证支付

错误

已放弃的会话

相关内容