# @easypayment/medusa-payment-paypal 中文文档 规范地址：https://npmcn.com/package/%40easypayment/medusa-payment-paypal/ 版本：1\.3\.3 npm 元数据更新时间：2026-11-05T10:55:25.589Z 中文译文更新时间：2026-11-13T04:18:37.613Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40easypayment/medusa-payment-paypal 原文对照：https://npmcn.com/package/%40easypayment/medusa-payment-paypal/?lang=original 项目主页：https://github.com/easypaymentplugins/medusa-paypal#readme 源码仓库：https://github.com/easypaymentplugins/medusa-paypal ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.4 MB，367 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=20 - 运行依赖：0 个 - peer 依赖：@medusajs/ui ^4\.0\.0，@medusajs/icons ^2\.12\.0，@medusajs/medusa ^2\.12\.0，@medusajs/admin-sdk ^2\.12\.0，@medusajs/framework ^2\.12\.0 - 首次发布：2026-03-26T04:35:42.175Z - 最新版本发布：2026-11-05T10:55:25.450Z - 近 30 天下载量：2995（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：63（近 12 个月 63 个） ## 中文简介 PayPal & 信用卡支付美杜莎 v2——PayPal按钮,主机卡字段,3D安全,以及一个管理员仪表板. 由PayPal合伙人所建. ## 安装 ```sh npm install @easypayment/medusa-payment-paypal ``` 也可以使用：`pnpm add @easypayment/medusa-payment-paypal`、`yarn add @easypayment/medusa-payment-paypal`、`bun add @easypayment/medusa-payment-paypal` ## README # 美杜莎付费Pal **接受你的美杜莎v2商店的PayPal和信用卡支付——由官方的PayPal合伙人建造.** [![npm version](https://img.shields.io/npm/v/@easypayment/medusa-payment-paypal?color=blue&label=npm)](https://www.npmjs.com/package/@easypayment/medusa-payment-paypal) [![npm downloads](https://img.shields.io/npm/dm/@easypayment/medusa-payment-paypal?color=blue&label=downloads)](https://www.npmjs.com/package/@easypayment/medusa-payment-paypal) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://npmcn.com/package/%40easypayment/medusa-payment-paypal/LICENSE) [![Medusa v2](https://img.shields.io/badge/Medusa-v2-9b59b6)](https://medusajs.com/) [![PayPal PPCP](https://img.shields.io/badge/PayPal-PPCP-003087)](https://developer.paypal.com/) * * * ## 你得到的东西 | 特性 | 细节 | | --- | --- | | 🔵 **付费按钮** | 点击 PayPal 为您的客户办理离职手续 | | 💳 **卡片付款** | 安全信用和借记卡字段,由PayPal(遵守PCI)托管 | | 🛠 **管理板** | 连接您的 PayPal 账户并管理 Medusa 管理器的全部内容 | | 🌍 **测试活模式( L)** | 在Sandbox里安全地尝试一切,然后开始直播 | | 🔐 **三维安全** | 额外卡片安全, 点击一次即可配置 | | 🔄 **设计可靠** | 付款由PayPal逐一核实——网路网路、网路网和安全网处理 | * * * ## 所需经费 - 美杜莎岛 **五维十二+** - 节点.js **20岁以上** - 邮递SQL * * * ## \* 安装 在您的 Medusa 后端文件夹中, 运行 : ```bash npm install @easypayment/medusa-payment-paypal ``` * * * ## \* 设置——5个步骤 ### 1\. 将插件添加到 `medusa-config.ts` ```ts import { loadEnv, defineConfig } from "@medusajs/framework/utils" loadEnv(process.env.NODE_ENV || "development", process.cwd()) export default defineConfig({ projectConfig: { databaseUrl: process.env.DATABASE_URL, http: { storeCors: process.env.STORE_CORS!, adminCors: process.env.ADMIN_CORS!, authCors: process.env.AUTH_CORS!, jwtSecret: process.env.JWT_SECRET || "supersecret", cookieSecret: process.env.COOKIE_SECRET || "supersecret", }, }, plugins: [ { resolve: "@easypayment/medusa-payment-paypal", options: {}, }, ], modules: [ { resolve: "@medusajs/medusa/payment", options: { providers: [ { // PayPal Buttons resolve: "@easypayment/medusa-payment-paypal/providers/paypal", id: "paypal", options: {}, dependencies: ["paypal_onboarding"], }, { // Card payments resolve: "@easypayment/medusa-payment-paypal/providers/paypal_card", id: "paypal_card", options: {}, dependencies: ["paypal_onboarding"], }, ], }, }, ], }) ``` ### 2\. 运行数据库迁移 ```bash npx medusa db:migrate ``` ### 3\. 连接您的 PayPal 账户 1. 启动你的美杜莎服务器 2. 打开 **Medusa 管理员 – 设置 – PayPal** 3. 选择 **沙盒** (测试)或 **现场直播** (实付款) 4. 点击 **连接到 PayPal** 并遵循步骤 就是这样——你的证书是自动保存的. Webhooks也为你注册了. > 优先手动设置? 点击 **手动插入证书** 并粘贴客户端的ID和机密 [开发者. paypal.com](https://developer.paypal.com/dashboard/)。 。 。 . ### 4\. 在您所在地区打开付费页 转到 **美杜莎管理者 设置 区域 区域 区域** 并能够: | 付款提供者 | 这是什么 | | --- | --- | | `pp_paypal_paypal` | 付费按钮 | | `pp_paypal_card_paypal_card` | 支付卡片 | ### 5\. 在仓库前端添加 PayPal 取出UI作为一个单独的软件包——安装在您的 **存储前端** 项目: 📦 **[@easypay/medusa-paypal-ui](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)** ——为Next.js storefronts而现成的PayPal组件,并有分步向导. * * * ## QQ 自定义( 可选的) 一切都在管理中 **Medusa 管理员 – 设置 – PayPal** - 更改立即适用,不需要重新启动: - **PayPal 设置** - 打开/关闭 PayPal、按钮颜色、形状和标签 - **高级卡付款** ——开启/关闭出卡支付,3D安全模式 - **其他设置** ——抓取与授权,在PayPal显示品牌名称,发票前缀 * * * ## 现场直播,我们推荐两件事 1. **`PAYPAL_ENCRYPTION_KEY`** —— 将此设定为您服务器环境中任意长的文本 。 您的 PayPal 证书随后被加密到数据库中 。 保管好钥匙:如果丢失,只需重新连接PayPal. 2. **`MEDUSA_BACKEND_URL`** ——将其设置在后端的公开地址上(如:. `https://api.mystore.com`因此,PayPal可以到你的店里进行付款通知. **高级选项** (对于开发者来说——没有这些东西,一切都是可行的) | 变量 | 默认 | 它会做什么 | | --- | --- | --- | | `STOREFRONT_URL` | _(如果列于 `STORE_CORS`(中文(简体) )_ | 用于 PayPal 返回/取消页面的存储前端地址( 也可以设置在 Admin) | | `PAYPAL_ENCRYPTION_STRICT` | `false` | `true` = 拒绝保存未加密的证书 | | `PAYPAL_SELLER_NONCE` | _(合作伙伴服务非ce)_ | 只有同时运行自己才能更改 `PAYPAL_PARTNER_SERVICE_URL`; 它必须匹配服务在其入职链接中设置的非值 | | `PAYPAL_ADMIN_ORIGIN` | 第一个 `ADMIN_CORS` 条目 | 将登入弹出限制为您的管理员 URL | | `PAYPAL_WEBHOOK_COMPLETE_CART` | `true` | 当付款成功时完成订单但买方浏览器关闭的安全网. `false` 关闭它 | | `PAYPAL_RATE_LIMIT_MAX` 编号 : `PAYPAL_RATE_LIMIT_WINDOW_MS` | _(关闭)_ 编号 : `60000` | 公开退票路线的可选请求限制 | | `PAYPAL_WEBHOOK_RATE_LIMIT_MAX` 编号 : `PAYPAL_WEBHOOK_RATE_LIMIT_WINDOW_MS` | _(关闭)_ 编号 : `60000` | 可选的 Webhook 端点请求限制( 独立于以上) | | `PAYPAL_WEBHOOK_REPLAY_WINDOW_MINUTES` | `60` | 拒绝比此更老的 Webhook 交付 | | `PAYPAL_WEBHOOK_STALE_PROCESSING_MS` | `300000` | 当重试任务重新选择中断的 Webhook 事件时 | | `PAYPAL_WEBHOOK_ID_LIVE` 编号 : `PAYPAL_WEBHOOK_ID_SANDBOX` | _(自动)_ | 手动 Webhook- id 覆盖( 通常自动) | | `PAYPAL_HTTP_TIMEOUT_MS` | `30000` | 呼叫 PayPal 的超时 | | `PAYPAL_CURRENCY` | `EUR` | 如果没有配置回落货币 | | `PAYPAL_ALERT_WEBHOOK_URLS` | _(未设定)_ | 接受操作提醒的逗号分隔 URL(包括已死字母的webhook事件) | | `PAYPAL_SETTINGS_CACHE_MS` | `15000` | 用于插件设置的流程中缓存读取; `0` 禁用 | | `PAYPAL_SEND_SHIPPING_ADDRESS` | `false` | `true` 根据PayPal的订单发送推车的货运地址(`SET_PROVIDED_ADDRESS`() 提高PayPal销售商保护资格 | | `PAYPAL_PARTNER_SERVICE_URL` | _(内置)_ | 覆盖连接流所使用的搭载伙伴服务 | | `PAYPAL_PARTNER_MERCHANT_ID_SANDBOX` 编号 : `PAYPAL_PARTNER_MERCHANT_ID_LIVE` | _(内置)_ | 覆盖用于登入的合伙人商号 | **缩入的牌 :** 当PayPal拒绝捕捉的时候, `/store/paypal/capture-order` 响应 `402` 与方便买方的 `message` 加结构化 `decline` 对象 - `{ code, message, retryable, avs_code?, cvv_code? }` ——因此商店面可以显示"资金不足,再试一张卡",并决定是否提供再试. **监测:** 操作计数器在 `paypal_metric` 表格; 记录每个网页 `paypal_webhook_event` 自动重试( 排出重试的事件为已死字母) **并被推为 `PAYPAL_ALERT_WEBHOOK_URLS`**); 审计事件作为 JSON 线路标记记录 `"log":"paypal_audit"` (机密编辑). * * * ## ++ 辅助 - 🐛 **找到窃听器了吗?** [打开一个问题](https://github.com/easypaymentplugins/medusa-paypal/issues) - 💡 **问题或特写请求?** [开始讨论](https://github.com/easypaymentplugins/medusa-paypal/discussions) - 🛍 **存储前置 UI 软件包 :** [@easypay/medusa-paypal-ui](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui) * * * ## 许可证 麻省理工学院 [轻松支付](https://www.npmjs.com/package/@easypayment/medusa-payment-paypal) ## 常见问题 ### @easypayment/medusa-payment-paypal 是什么？ PayPal & 信用卡支付美杜莎 v2——PayPal按钮,主机卡字段,3D安全,以及一个管理员仪表板\. 由PayPal合伙人所建\. ### 如何安装 @easypayment/medusa-payment-paypal？ 在项目目录运行 npm install @easypayment/medusa-payment-paypal，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@medusajs/medusa（^2\.12\.0）、@medusajs/framework（^2\.12\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @easypayment/medusa-payment-paypal 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @easypayment/medusa-payment-paypal 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @easypayment/medusa-payment-paypal 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @easypayment/medusa-payment-paypal 可以商用吗？ @easypayment/medusa-payment-paypal 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @easypayment/medusa-payment-paypal 的下载量有多少？ 根据 npm 官方下载统计，@easypayment/medusa-payment-paypal 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,995 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @easypayment/medusa-payment-paypal 还在维护吗？ 最新版本 1\.3\.3 发布于 2026/11/05（8 天前）；至今共发布 63 个版本，其中过去 12 个月发布了 63 个；首次发布于 2026/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。