# @adyen/react-native 中文文档

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

版本：2\.14\.0
npm 元数据更新时间：2026-11-02T15:25:22.824Z
中文译文更新时间：2026-11-05T18:03:17.119Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：954 kB，706 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：expo \>=52，react \*，react-native \>=0\.76\.0
- 首次发布：2022-03-10T17:58:13.665Z
- 最新版本发布：2026-11-02T15:25:22.360Z
- 近 30 天下载量：108300（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 8 个）

## 中文简介

包装 Adyen 退出和组件, 用于iOS和Android, 方便使用 React Industrial

## 安装

```sh
npm install @adyen/react-native
```

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

## README

[![npm version](https://img.shields.io/npm/v/@adyen/react-native.svg?style=flat-square)](https://www.npmjs.com/package/@adyen/react-native) [![Adyen iOS](https://img.shields.io/badge/ios-v5.27.0-brightgreen.svg)](https://github.com/Adyen/adyen-ios/releases/tag/5.27.0) [![Adyen Android](https://img.shields.io/badge/android-v5.22.0-brightgreen.svg)](https://github.com/Adyen/adyen-android/releases/tag/5.22.0) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Adyen_adyen-react-native&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Adyen_adyen-react-native)

> \[重要\] **反应原生新架构支持**  
> 
> 这个 **新建筑** 为 React Industrial 提供版本支持 **0.76.0及以上(含)**。 。 。 .

> \[重要\]
> 
> Adyen Android SDK 5.2.2.0需要克特林 2.3 (2.20 on Expo SDK 54),Android API 36和Android Gradle插件 8.9.1. 它由React Independent 0.79和Expo SDK 54.支持.
> 
> 见 [兼容性](https://npmcn.com/package/%40adyen/react-native/docs/Compatibility.md#adyen-android-sdk-5220-kotlin-and-android-sdk-requirements) 用于设定您的“ 反应原生” 或“ 博览会” 版本 。 同一文档为官方不支持的React Industrial版本保留了0.74以下的注释.

![React Native Logo](https://user-images.githubusercontent.com/2648655/198584674-f0c46e71-1c21-409f-857e-77acaa4daae0.png)

# Adyen 反应原生

Adyen React Introduct为您提供构件,为您的购物者创造出票体验,允许他们使用自己选择的支付方法支付.

您可以通过两种方式与Adyen React Industrial融合:

-   [下潜](https://docs.adyen.com/online-payments/react-native/drop-in): React Industrial iOS和Android Adyen Drop-in - 一个全能的解决方案,是接受在你的 React Industrial app上付款的最快捷方式.
-   [构成部分](https://docs.adyen.com/online-payments/react-native/components): 原生iOS和Android Adyen组件的回放原生包装器 - 每个支付方法一个组件,可以与你自己的支付流量结合.

## 目录

-   [先决条件](https://npmcn.com/package/%40adyen/react-native/#readme-prerequisites)
-   [安装](https://npmcn.com/package/%40adyen/react-native/#readme-installation)
    -   [博览](https://npmcn.com/package/%40adyen/react-native/#readme-expo-integration)
    -   [手动整合](https://npmcn.com/package/%40adyen/react-native/#readme-manual-integration)
-   [使用量](https://npmcn.com/package/%40adyen/react-native/#readme-usage)
    -   [配置](https://npmcn.com/package/%40adyen/react-native/#readme-configuration)
    -   [流程](https://npmcn.com/package/%40adyen/react-native/#readme-sessions-flow)
    -   [高级流程](https://npmcn.com/package/%40adyen/react-native/#readme-advanced-flow)
    -   [处理动作](https://npmcn.com/package/%40adyen/react-native/#readme-handling-actions)
-   [文档](https://npmcn.com/package/%40adyen/react-native/#readme-documentation)
-   [捐款](https://npmcn.com/package/%40adyen/react-native/#readme-contributing)
-   [支助](https://npmcn.com/package/%40adyen/react-native/#readme-support)
-   [许可证](https://npmcn.com/package/%40adyen/react-native/#readme-license)

## 先决条件

-   [Adyen 测试账户](https://www.adyen.com/signup)
-   [API 密钥](https://docs.adyen.com/development-resources/how-to-get-the-api-key)
-   [客户端密钥](https://docs.adyen.com/development-resources/client-side-authentication#get-your-client-key)

# 安装

添加 `@adyen/react-native` 切换到您的 React 原生项目 :

```bash
yarn add @adyen/react-native
```

## 博览会整合

> \[大
> 
> 此库与 Expo Go 不符 。 专门设计用于: [连续的土著一代](https://docs.expo.dev/workflow/overview/#continuous-native-generation-cng)。 。 。 .

添加 `@adyen/react-native` 您的插件 `app.json`数字 :

```json
{
  "expo": {
    "plugins": ["@adyen/react-native"]
  }
}
```

为Android安装 `expo-build-properties` 并设定您的 Expo SDK 的 Kotlin 和 Android API 值 [兼容性](https://npmcn.com/package/%40adyen/react-native/docs/Compatibility.md#expo)。 。 。 .

**插件配置选项**

| 选项 | 说明 |
| --- | --- |
| `merchantIdentifier` | 将 ApplePay Merchant ID 设定为您的 iOS 应用程序的应享权利文件 。 默认空出. |
| `useFrameworks` | 调整 `import` 在iOS上,以防出现 `Podfile` 已经 `use_frameworks!` 启用 . |

**所有选项的示例:**

```json
{
  "expo": {
    "plugins": [
      [
        "@adyen/react-native",
        {
          "merchantIdentifier": "merchant.com.my-merchant-id",
          "useFrameworks": true
        }
      ]
    ]
  }
}
```

> \[TIP\]
> 
> 如果您正面临插件的问题, 请预先构建您的应用程序并调查生成的文件 :
> 
> ```bash
> npx expo prebuild --clean
> ```

## 手动整合

> \[注\]
> 
> 关于目标C和爪哇一体化,见 [遗留文件](https://github.com/Adyen/adyen-react-native/tree/2.9.0?tab=readme-ov-file#ios-integration)。 。 。 .

**iOS 设置**

1.  运行 `pod install`
    
2.  添加 `returnURL` 处理器到您的 `AppDelegate.swift`数字 :
    

```swift
import Adyen

// ...

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return RedirectComponent.applicationDidOpen(from: url)
}
```

如果使用 `RCTLinkingManager` 或其他深接技术,地点 `ADYRedirectComponent.applicationDidOpen` 在他们面前:

```swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return RedirectComponent.applicationDidOpen(from: url) || RCTLinkingManager.application(app, open: url, options: options)
}
```

通用链接支持 :

```swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
       let url = userActivity.webpageURL,
       RedirectComponent.applicationDidOpen(from: url) {
        return true
    }
    return RCTLinkingManager.application(application, continue: userActivity, restorationHandler: restorationHandler)
}
```

3.  添加 [自定义 URL 方案](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) 给您的应用程序.
    
4.  **对于 ApplePay :** 跟着 [启用 iOS 的 ApplePay](https://docs.adyen.com/payment-methods/apple-pay/enable-apple-pay?tab=i_os_2) 向导.
    

**Android 设置**

1.  设置 Kotlin, Android API 级别, 并在 React Industrial 0.79 上安装 Android Gradle 插件 `android/build.gradle` 列于 [兼容性](https://npmcn.com/package/%40adyen/react-native/docs/Compatibility.md#bare-react-native)。 。 。 .
    
2.  向您提供退出活动 `AdyenCheckout` 内 `MainActivity.kt`数字 :
    

```kotlin
import com.adyenreactnativesdk.AdyenCheckout
import android.os.Bundle

// ...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(null)
    AdyenCheckout.setLauncherActivity(this)
}
```

3.  添加 `intent-filter` 转到您的退出活动( 独立组件):

```xml
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" android:path="/payment" />
</intent-filter>
```

4.  添加 `returnURL` 独立方向调整组件的处理器 `MainActivity.kt`数字 :

```kotlin
import android.content.Intent

// ...

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    AdyenCheckout.handleIntent(intent)
}
```

5.  确保您的应用主题扩展 `Theme.MaterialComponents`数字 :

```xml
<style name="AppTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
    <!-- Your configuration here -->
</style>
```

# 使用量

为了解Adyen工程的预建UI组件,您可以遵循 [我们的文件](https://docs.adyen.com/online-payments/prebuilt-ui)。 。 。 .

## 配置

欲进一步了解其他配置,请参见 [完整列表](https://npmcn.com/docs/Configuration.md)。 。 。 . 所需配置实例:

```typescript
import { Configuration } from '@adyen/react-native';

const configuration: Configuration = {
  environment: 'test', // When you're ready to accept real payments, change the value to a suitable live environment.
  clientKey: '{YOUR_CLIENT_KEY}',
  countryCode: 'NL',
  amount: { currency: 'EUR', value: 1000 }, // Value in minor units
  returnUrl: 'myapp://payment', // See description below.
};
```

### 返回 URL

> \[大
> 
> 打开 `config` 使用自定义的 URL 方案或您的应用程序的 App/ Universal 链接.

| 假设 | 如何使用 |
| --- | --- |
| 高级流量 | 
期间 `onSubmit(data, component, extras)` 通过 `"returnUrl": data.returnUrl` 将制作 `\payments` API电话.

 |
| 会话流 | 

来做 `\sessions` API 调用 `AdyenDropIn.getReturnURL()` 要获取 `returnUrl`。 。 。 .

```js
const returnUrl = Platform.select({
  ios: 'myapp://payment',
  android: await AdyenDropIn.getReturnURL(),
});
```

 |

## 开始支付部分

用于 `@adyen/react-native` 您可以使用我们的助手组件 `AdyenCheckout` 和助手的函数来自 `useAdyenCheckout` 具有独立组件:

```javascript
import { useAdyenCheckout } from '@adyen/react-native';

const MyCheckoutView = () => {
  const { start } = useAdyenCheckout();

  return (
    <Button
      title="Open DropIn"
      onPress={() => {
        start('dropIn');
      }}
    />
  );
};
```

### 流程

> \[大
> 
> **回忆你的回电** 与 `useCallback` 以防止不必要的重报和事件听众重新登记。 内置函数会导致性能问题.

```javascript
import { AdyenCheckout } from '@adyen/react-native';
import { useCallback } from 'react';

const onComplete = useCallback((result, component) => {
  // Payment was completed - call `component.hide(true)` to dismiss the payment UI.
  // Call /sessions/(sessionId)?sessionResult={result} API to get more information about the payment outcome.
}, []);

const onError = useCallback((error, component) => {
  // Payment was terminated by shopper or encountered an error
  // Call `component.hide(false)` to dismiss the payment UI.
}, []);

<AdyenCheckout
  config={configuration}
  session={session}
  onComplete={onComplete}
  onError={onError}
>
  <MyCheckoutView />
</AdyenCheckout>;
```

### 高级流程

```javascript
import { AdyenCheckout } from '@adyen/react-native';
import { useCallback } from 'react';

const onSubmit = useCallback((data, component) => {
  // Call your server to make the `/payments` request
  // Pass `returnUrl: data.returnUrl` for cross-platform redirect flow
  // If response contains `action`, call `component.handle(response.action)`
  // Otherwise, call `component.hide(true | false)` to dismiss the payment UI
}, []);

const onAdditionalDetails = useCallback((paymentData, component) => {
  // Call your server to make the `/payments/details` request
  // Call `component.hide(true | false)` to dismiss the payment UI
}, []);

const onError = useCallback((error, component) => {
  // Payment was terminated by shopper or encountered an error
  // Call `component.hide(false)` to dismiss the payment UI
}, []);

<AdyenCheckout
  config={configuration}
  paymentMethods={paymentMethods}
  onSubmit={onSubmit}
  onAdditionalDetails={onAdditionalDetails}
  onError={onError}
>
  <MyCheckoutView />
</AdyenCheckout>;
```

## 处理动作

一些支付方法要求shopper采取额外行动,例如:扫描QR代码,用3D Security认证支付,或者登录他们的银行网站完成支付. 为了应对这些额外的前端挑战,使用 `nativeComponent.handle(action)` 从 `onSubmit` 调用.

```javascript
const handleSubmit = (paymentData, nativeComponent) => {
  server.makePayment(paymentData)
    .then((response) => {
      if (response.action) {
        nativeComponent.handle(response.action);
      } else {
        nativeComponent.hide(response.result);
      }
    });
};

<AdyenCheckout
  ...
  onSubmit={handleSubmit}
  >
    ...
</AdyenCheckout>
```

### 独立行动处理

仅限API的整合 `AdyenAction.handle` 可以用来. 在你开始之前,确保你跟随所有 [iOS 整合](https://npmcn.com/package/%40adyen/react-native/#readme-ios-integration) 财务报告和审定财务报表 [Android 集成系统](https://npmcn.com/package/%40adyen/react-native/#readme-android-integration) 步骤.

示例

```js
import { AdyenAction } from '@adyen/react-native';

const data = await AdyenAction.handle(apiResponse.action, { environment: 'test', clientKey: '{YOUR_CLIENT_KEY}');
result = await ApiClient.paymentDetails(data);
```

# 文档

-   [配置](https://npmcn.com/docs/Configuration.md)
-   [本地化](https://npmcn.com/docs/Localization.md)
-   [UI 自定义](https://npmcn.com/docs/Customization.md)
-   [错误代码](https://npmcn.com/docs/Error%20codes.md)
-   [降入文档](https://docs.adyen.com/online-payments/react-native/drop-in)
-   [构成部分文件](https://docs.adyen.com/online-payments/react-native/components)

## 捐款

我们强烈鼓励你们与我们一道为这个存放处作出贡献,以便每个人都能从以下各方面获益:

-   新功能和功能
-   解决错误修正和问题
-   任何一般性改进

读我们 [**捐款准则**](https://npmcn.com/package/%40adyen/react-native/CONTRIBUTING.md) 找出办法.

# 支助

如果你有特性请求 或发现错误或技术问题, [创建 GitHub 问题](https://github.com/Adyen/adyen-react-native/issues/new/choose)关于其他问题,请通过 [客户区](https://ca-live.adyen.com/ca/ca/contactUs/support.shtml) 通过电子邮件: [支持@ adyen.com](mailto:support@adyen.com)

# 许可证

麻省理工学院执照. 更多信息,请参见 [自由主义](https://npmcn.com/package/%40adyen/react-native/LICENSE) 文档.

## 常见问题

### @adyen/react-native 是什么？

包装 Adyen 退出和组件, 用于iOS和Android, 方便使用 React Industrial

### 如何安装 @adyen/react-native？

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

### @adyen/react-native 支持 TypeScript 吗？

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

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

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

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

@adyen/react-native 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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