# @alphabite/medusa-paypal 中文文档

规范地址：https://npmcn.com/package/%40alphabite/medusa-paypal/

版本：0\.2\.6
npm 元数据更新时间：2026-04-17T07:57:51.692Z
中文译文更新时间：2026-11-06T13:55:36.367Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40alphabite/medusa-paypal
原文对照：https://npmcn.com/package/%40alphabite/medusa-paypal/?lang=original
项目主页：https://github.com/alphabite-dev/medusa-paypal#readme
源码仓库：https://github.com/alphabite-dev/medusa-paypal

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

- 包体积（解压后）：79.2 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：@medusajs/admin-sdk 2\.13\.6，@medusajs/cli 2\.13\.6，@medusajs/framework 2\.13\.6，@medusajs/icons 2\.13\.6，@medusajs/medusa 2\.13\.6，@medusajs/test-utils 2\.13\.6，@medusajs/ui 4\.0\.4，@mikro-orm/cli 6\.4\.3，@mikro-orm/core 6\.4\.3，@mikro-orm/knex 6\.4\.3，@mikro-orm/migrations 6\.4\.3，@mikro-orm/postgresql 6\.4\.3，awilix ^8\.0\.1，pg ^8\.13\.0
- 首次发布：2025-06-11T16:49:04.159Z
- 最新版本发布：2026-04-17T07:57:51.526Z
- 近 30 天下载量：3078（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 2 个）

## 中文简介

阿尔法比特的 Medusa Paypal 插件

## 安装

```sh
npm install @alphabite/medusa-paypal
```

也可以使用：`pnpm add @alphabite/medusa-paypal`、`yarn add @alphabite/medusa-paypal`、`bun add @alphabite/medusa-paypal`

## README

# 美杜莎 PayPal 插件

[![Discord](https://img.shields.io/badge/Join%20our%20Discord-Community%20Server-7289da.svg)](https://discord.gg/ZgBCYTMaVQ) [![Documentation](https://img.shields.io/badge/Read%20the%20full-Documentation-blue.svg)](https://medusa-docs.alphabite.io/docs/category/paypal)

Alphabite PayPal 插件将 PayPal 支付处理整合到您的美杜莎商店中 。 它处理各种付款流程,包括收取付款、管理退款以及确保有力的错误处理.

* * *

## 版本兼容性

选择匹配您 Medusa 后端版本的插件版本 :

| 美杜莎版本 | 插件版本 | 安装命令 |
| --- | --- | --- |
| `>= 2.13.*` | `latest` | `npm install @alphabite/medusa-paypal` |
| `< 2.13.*` | `0.2.5` | `npm install @alphabite/medusa-paypal@0.2.5` |

### 说明

-   **美杜莎2.13.\*及以上:** 安装插件的最新版本 。 这是积极维护的放出,并与最新的美杜莎API相容需要.
-   **2.13.\*以下为美杜莎:** 将插件绑入版本 `0.2.5`. 后期插件版本依赖美杜莎2.13中引入的API,不会对更古老的后端工作.

在安装前, 请验证您的美杜莎版本 :

```bash
npm list @medusajs/medusa
```

然后安装匹配插件版本 :

```bash
# Medusa >= 2.13.* (latest)
npm install @alphabite/medusa-paypal

# Medusa < 2.13.* (pinned)
npm install @alphabite/medusa-paypal@0.2.5
```

> QQ 在本地、 中继和生产中使用相同的插件版本, 以避免运行时间出错 .

* * *

# 美杜莎 PayPal 插件

[![Discord](https://img.shields.io/badge/Join%20our%20Discord-Community%20Server-7289da.svg)](https://discord.gg/ZgBCYTMaVQ) [![Documentation](https://img.shields.io/badge/Read%20the%20full-Documentation-blue.svg)](https://medusa-docs.alphabite.io/docs/category/paypal)

Alphabite PayPal 插件将 PayPal 支付处理整合到您的美杜莎商店中 。 它处理各种付款流程,包括收取付款、管理退款以及确保有力的错误处理.

* * *

## 目录

-   [\* 核心特征](https://npmcn.com/package/%40alphabite/medusa-paypal/#readme--core-features)
-   [兼容性](https://npmcn.com/package/%40alphabite/medusa-paypal/#readme--compatibility)
-   [常见案件](https://npmcn.com/package/%40alphabite/medusa-paypal/#readme--common-use-cases)
-   [\* 安装](https://npmcn.com/package/%40alphabite/medusa-paypal/#readme--installation)
-   [QQ 插件选项](https://npmcn.com/package/%40alphabite/medusa-paypal/#readme--plugin-options)
-   [页:1](https://npmcn.com/package/%40alphabite/medusa-paypal/#readme--documentation)

* * *

## \* 核心特征

-   QQ 无缝支付整合
-   处理各种 PayPal 错误状态
-   ++ 支持直接从美杜莎管理员处退款
-   QQ 在同一支付意图范围内为每次支付尝试创建新订单ID
-   \* 选择性地将货运和客户数据纳入PayPal订单

* * *

## 兼容性

-   **后端 :** 美杜莎 v2+ (英语)
-   **前端 :** 框架不可知性( 包含 PayPal 的 SDK)
-   **管理员 :** 退款功能并入美杜莎行政

* * *

## 常见案件

-   接受对产品和服务的付款
-   有效管理付款和退款
-   确保以全面处理错误的方式进行稳健的付款处理

* * *

## 页:1

完整文件请访问 [PayPal 插件文档](https://medusa-docs.alphabite.io/docs/category/paypal)。 。 。 .

* * *

* * *

# \* 安装

这个向导在您的美杜莎后端安装和配置 Alphabite PayPal 插件 .

* * *

## 1\. 安装插件

通过 npm 安装软件包 :

```bash
npm install @alphabite/medusa-paypal
```

* * *

## 2\. 登记插件

将插件添加到您的 `medusa.config.ts` 或者说 `medusa-config.js`数字 :

```ts
{
  plugins: [
    {
      resolve: "@alphabite/medusa-paypal",
      options: {
        clientId: process.env.PAYPAL_CLIENT_ID,
        clientSecret: process.env.PAYPAL_CLIENT_SECRET,
        isSandbox: process.env.PAYPAL_IS_SANDBOX === "true",
        webhookId: process.env.PAYPAL_WEBHOOK_ID,
        includeShippingData: false,
        includeCustomerData: false,
      },
    },
  ],
  modules:[
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "./src/modules/paypal",
            id: "paypal",
            options: {
              clientId: process.env.PAYPAL_CLIENT_ID,
              clientSecret: process.env.PAYPAL_CLIENT_SECRET,
              isSandbox: process.env.PAYPAL_SANDBOX === "true",
              webhookId: process.env.PAYPAL_WEBHOOK_ID,
              includeShippingData: false,
              includeCustomerData: false,
            },
          },
        ],
      },
    },
  ]
};
```

* * *

## QQ 插件选项

下列选项可以传递到您的 PayPal 插件 `medusa-config.js` 或者说 `medusa.config.ts` 文件 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `clientId` | `string` |  | 要求。 您的 PayPal API 客户端 ID . |
| `clientSecret` | `string` |  | 要求。 你的PayPal API客户端秘密. |
| `isSandbox` | `boolean` | `true` | 是否使用 PayPal Sandbox 环境进行测试 . |
| `webhookId` | `string` |  | 可选的 您的 PayPal 网页识别码 。 如果提供,则能够确认所收付款. |
| `includeShippingData` | `boolean` | `false` | 可选的 若为 `true`,从存储前端订单中运出的数据会被添加到PayPal订单中. |
| `includeCustomerData` | `boolean` | `false` | 可选的 若为 `true`,店面订单的客户数据将添加到PayPal订单中. |

* * *

## 兼容性

-   要求数 **美杜莎 v2 (英语)**
-   与JS和TypeScript项目兼容

* * *

## 下一个步骤

👉 [配置指南](https://medusa-docs.alphabite.io/docs/category/paypal) 👉 [加入我们的Discord社区](https://discord.gg/ZgBCYTMaVQ) 用于更快的支持

* * *

## QQ 前端集成

本指南解释如何将 PayPal 支付流量整合到您的 Next.js storefront 中使用 `@paypal/react-paypal-js`。 。 。 .

### 1\. 安装附属设施

安装 PayPal 官方反应 SDK :

```bash
npm install @paypal/react-paypal-js
```

### 2\. 环境变量

请确保您在您的环境变量中提供公共 PayPal 客户端标识 :

```env
NEXT_PUBLIC_PAYPAL_CLIENT_ID=your_paypal_client_id
```

### 3\. 执行情况概览

整合涉及将您的支付表以 `PayPalScriptProvider` 财务报告和审定财务报表 `PayPalCardFieldsProvider`。 。 。 .

#### 关键部件 :

-   **`PayPalScriptProvider`**:装入PayPal SDK脚本.
-   **`PayPalCardFieldsProvider`**:管理状态并调回卡片字段.
-   **`PayPalCardFieldsForm`**: 渲染安全输入字段.

### 4\. 代码示例

以下是如何实施PayPal支付部分的简化结构,其依据是 `shose-storefront/src/collections/form/checkout/paypal.tsx`数字 :

```tsx
import {
  PayPalCardFieldsForm,
  PayPalCardFieldsProvider,
  PayPalScriptProvider,
  usePayPalCardFields,
} from "@paypal/react-paypal-js";
import { useState, useEffect } from "react";
// Import your internal hooks/utilities (e.g., sdk, usePlaceOrder)

export const PayPalPayment = ({ cart, onPaymentCompleted }) => {
  const [clientToken, setClientToken] = useState(null);

  // 1. Fetch Client Token from your backend
  useEffect(() => {
    const fetchClientToken = async () => {
      const response = await sdk.client.fetch("/store/paypal/client-token", {
        method: "POST",
      });
      setClientToken(response.clientToken);
    };
    fetchClientToken();
  }, []);

  // 2. Define Callbacks
  const createOrder = async () => {
    // Logic to initiate payment session and return order_id
    // e.g., sdk.store.payment.initiatePaymentSession(cart, { provider_id: "pp_paypal_paypal" })
    return order_id;
  };

  const onApprove = async (data) => {
    // Logic to finalize order after PayPal approval
    await placeOrder();
    onPaymentCompleted();
  };

  if (!clientToken) return <div>Loading...</div>;

  return (
    <PayPalScriptProvider
      options={{
        clientId: process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID,
        components: "card-fields",
        currency: "EUR",
        intent: "capture",
        dataClientToken: clientToken,
      }}
    >
      <PayPalCardFieldsProvider
        createOrder={createOrder}
        onApprove={onApprove}
        style={{
          input: {
            "font-size": "14px",
            "font-family": "Inter, sans-serif",
            color: "#111827",
          },
        }}
      >
        <PayPalCardFieldsForm />
        <SubmitButton />
      </PayPalCardFieldsProvider>
    </PayPalScriptProvider>
  );
};

const SubmitButton = () => {
  const { cardFieldsForm } = usePayPalCardFields();

  const handleClick = async () => {
    if (cardFieldsForm) {
      await cardFieldsForm.submit();
    }
  };

  return <button onClick={handleClick}>Pay Now</button>;
};
```

### 5\. 付款流程详情

1.  **客户端托肯**时间轴: **必须** 从您的 Medusa 后端获取客户端符号( Name`/store/paypal/client-token`并传递给 `PayPalScriptProvider`。这授权客户端代表您的账户采取行动.
2.  **创建顺序**编号: `createOrder` 当用户试图支付时会触发回调。 它应该在美杜莎启动付款会话,并归还支付保单的身份证.
3.  **核准**编号: `onApprove` 在 PayPal 成功授权支付后恢复调用 。 使用此来完成美杜莎语中的顺序( 如, `placeOrder`) (中文(简体) ).

## 常见问题

### @alphabite/medusa-paypal 是什么？

阿尔法比特的 Medusa Paypal 插件

### 如何安装 @alphabite/medusa-paypal？

在项目目录运行 npm install @alphabite/medusa-paypal，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@medusajs/admin-sdk（2\.13\.6）、@medusajs/cli（2\.13\.6）、@medusajs/framework（2\.13\.6）、@medusajs/icons（2\.13\.6）、@medusajs/medusa（2\.13\.6）、@medusajs/test-utils（2\.13\.6）、@medusajs/ui（4\.0\.4）、@mikro-orm/cli（6\.4\.3）、@mikro-orm/core（6\.4\.3）、@mikro-orm/knex（6\.4\.3）、@mikro-orm/migrations（6\.4\.3）、@mikro-orm/postgresql（6\.4\.3）、awilix（^8\.0\.1）、pg（^8\.13\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alphabite/medusa-paypal 支持 TypeScript 吗？

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

### @alphabite/medusa-paypal 支持 ESM 还是 CommonJS？

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

### @alphabite/medusa-paypal 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @alphabite/medusa-paypal 可以商用吗？

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

### @alphabite/medusa-paypal 的下载量有多少？

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

### @alphabite/medusa-paypal 还在维护吗？

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