# @dodopayments/react-native-checkout 中文文档

规范地址：https://npmcn.com/package/%40dodopayments/react-native-checkout/

版本：1\.2\.1
npm 元数据更新时间：2026-08-24T07:37:08.428Z
中文译文更新时间：2026-11-12T14:35:16.753Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dodopayments/react-native-checkout
原文对照：https://npmcn.com/package/%40dodopayments/react-native-checkout/?lang=original
项目主页：https://github.com/dodopayments/dodopayments-mobile-sdk/tree/main/react-native
源码仓库：https://github.com/dodopayments/dodopayments-mobile-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：141 kB，45 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \>=0\.77\.0
- 首次发布：2026-07-27T12:43:15.846Z
- 最新版本发布：2026-08-24T07:37:07.941Z
- 近 30 天下载量：6229（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Open Dodo Pays在 React Introduct 的系统浏览器标签中托管了退出.

## 安装

```sh
npm install @dodopayments/react-native-checkout
```

也可以使用：`pnpm add @dodopayments/react-native-checkout`、`yarn add @dodopayments/react-native-checkout`、`bun add @dodopayments/react-native-checkout`

## README

# Dodo 付款检查 反演原生 SDK

在系统浏览器标签中 Open Dodo Pays 托管了退出 (单位:千美元)`SFSafariViewController` 在 iOS 上, Android 上的自定义标签),来自 React Industrial 从一个电话得到一个干净的结果。 土生土长 iOS/Android cores – 没有自己的检出逻辑.

涡轮模块, **仅新建架构**,反应原生0.77+. 所需经费: iOS 16+,Android minSdk 24. (英语).

> **说明:** 你的Android应用软件必须用 `compileSdk` 34岁或以上 这是AAR的AndroidX文物元数据中 宣布的地板 本地核心取决于(`androidx.activity`, (中文(简体) ), `androidx.browser`, (中文(简体) ), `androidx.core`) (中文(简体) ). 这个模块是自己的 `compileSdkVersion` 默认为35并 跟着你的作品 `rootProject.ext.compileSdkVersion` 当设置。 那边 没有 Kotlin Gradle 插件或 AGP 楼层 超出您的反射原生 版本已经强制要求 — RN 0.79的默认值( Kotlin 2. 0.21 / AGP 8. 8. 8.2) 足够了.

## 安装

```sh
npm i @dodopayments/react-native-checkout
```

-   **机器人:** 自动链接。 拉动 `com.dodopayments.api:checkout-android` 从马文.
-   **iOS: (英语)** `cd ios && pod install`。Swift核心被捆绑在软件包中.
-   **展览 :** 开发只建(不是Expo Go)。 将您的回调方案传递给 配置插件, 以预建线条 Android + iOS :
    
    ```json
    {
      "expo": {
        "scheme": "myapp",
        "plugins": [
          [
            "@dodopayments/react-native-checkout",
            { "scheme": "myappcheckout" }
          ]
        ]
      }
    }
    ```
    
    然后运行 `npx expo prebuild` (或重建dev客户端). 计划必须匹配 `returnUrl` (例如:. `myappcheckout://return`)必须不同于 `expo.scheme`, (中文(简体) ), 它已经在主要活动上注册.

## 设置

注册回调的 URL 方案, 操作系统将退出返回到 你的应用程序。 打开 **博览**,上面的配置插件对两个平台都这样做—— 您仍然需要iOS `Linking` (见Use).

打开 **赤色反应原生**数字 :

-   **iOS: (英语)** 在 Info.plist 中为您的方案添加一个 URL 类型,并转发到 应用程序的 URL `Linking` 处理进入 `DodoCheckout.handleOpenURL(url)` —— 说 `SFSafariViewController` 没有 用于获取其返回 URL 的处理中方式.
    
-   **机器人:** 设定您的回调方案为 Gradle 显示占位符 android核心本身的显示 已经宣布了方向 活动的意图过滤器, 所以这个属性是整个设置成本:
    
    ```kotlin
    android {
        defaultConfig {
            manifestPlaceholders["dodoCallbackScheme"] = "myappcheckout"
        }
    }
    ```
    

## 使用

```ts
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
  returnUrl: 'myappcheckout://return', // scheme must be registered (see Setup)
  onEvent: (e) => console.log(e.type),  // logging only — never decide outcome from events
});

switch (result.status) {
  case 'succeeded': /* UI only — confirm server-side */ break;
  case 'failed':    break;
  case 'cancelled': await reconcileAbandonedSession(); break; // outcome unknown — NOT a failure
  case 'pending':   await reconcileAbandonedSession(); break; // may be unparsed, not just async
  case 'expired':   break;
}
```

## 结果是一个UI提示,而不是付款证明

这个SDK从不调用多多API,也不持有API密钥. 允许您访问 后端从 webhook (`payment.succeeded` 编号 : `subscription.active`) (中文(简体) ).

## 核实付款情况

确认您后端的每笔付款, 而不是移动结果 :

-   **网页**: Dodo 付款当付款时会拨打后端 成功或订阅激活。 检查 [网络用户指南](https://docs.dodopayments.com/developer-resources/webhooks)。 。 。 .
-   **核查 API**: 抬头看 `paymentId` 用你的密钥通过 [获取付款详情](https://docs.dodopayments.com/api-reference/payments/get-payments-1)。 。 。 .

## `cancelled` 不是失败

`cancelled` 表示用户在返回任何 URL 到达之前解除了浏览器, 所以SDK从未得知结果. **可能已经付了.** A 类 在主机“ 付款成功” 页面计数时, 付费然后点击QQ的用户 减少它的再定向输出 `cancelled`无法分辨 SDK的一面,来自一个不付费而关闭浏览器的用户.

在这里展示"付账失败" 告诉付费客户他们的钱消失了. 解决它:SDK为这个案子保留会议记录.

## 放弃的会议

当 SDK 没有看到返回的 URL 时, 会话会保留在记录中 决心取得持久结果——应用程序(或联署材料捆绑)被杀死 中途退赛,而约已失约, `start` 已解决 `cancelled`,或者说它 已解决 `pending` 从无法解析的返回 URL 而不是真正的同步 支付方法。 调和服务器侧面, 无论是在下一个挂载上还是紧接着一个 `cancelled` 或者说 `pending` 结果 :

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

async function reconcileAbandonedSession() {
  const abandoned = await DodoCheckout.getAbandonedSession();
  if (!abandoned) return; // nothing in flight

  // Ask *your* backend what happened to abandoned.sessionId — it has the
  // webhook (`payment.succeeded`) or can call Get Payment Detail with your
  // secret key. Show a spinner while you wait; an async method may still be
  // settling, so treat "no record yet" as pending, not failed — and only
  // clear the record once you have a terminal outcome, or a later retry
  // has nothing left to reconcile against if this one comes back.
  const outcome = await myBackend.outcomeForSession(abandoned.sessionId);
  if (outcome.isTerminal) {
    await DodoCheckout.clearAbandonedSession();
  }
  show(outcome);
}
```

## 自定义

退出浏览器的工具栏、按钮和颜色方案可以通过 `customization` 打开 `start(...)`见 [外观自定义文件](https://docs.dodopayments.com/developer-resources/sdks/react-native#appearance-customization) 用于所有可用的选项.

## 错误

`start` 以 `CheckoutError` (单位:千美元)`.code` 这是其中之一 `INVALID_CHECKOUT_URL`, (中文(简体) ), `INVALID_RETURN_URL`, (中文(简体) ), `ALREADY_IN_PROGRESS`, (中文(简体) ), `PLATFORM_ERROR`仅用于滥用 或平台失效。 取消或拒绝付款是 **结果** (单位:千美元)`cancelled` 编号 : `failed`绝不拒绝.

## 地方发展

```sh
./scripts/sync-ios-core.sh   # vendor ../swift into ios/DodoCore for the pod
npm run typecheck && npm test
```

## 常见问题

### @dodopayments/react-native-checkout 是什么？

Open Dodo Pays在 React Introduct 的系统浏览器标签中托管了退出\.

### 如何安装 @dodopayments/react-native-checkout？

在项目目录运行 npm install @dodopayments/react-native-checkout，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\>=0\.77\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dodopayments/react-native-checkout 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dodopayments/react-native-checkout 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dodopayments/react-native-checkout 可以商用吗？

@dodopayments/react-native-checkout 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dodopayments/react-native-checkout 的下载量有多少？

根据 npm 官方下载统计，@dodopayments/react-native-checkout 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,229 次，日均约 208 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dodopayments/react-native-checkout 还在维护吗？

最新版本 1\.2\.1 发布于 2026/08/24（2 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/07/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。