美杜莎 PayPal 插件
Alphabite PayPal 插件将 PayPal 支付处理整合到您的美杜莎商店中 。 它处理各种付款流程,包括收取付款、管理退款以及确保有力的错误处理.
版本兼容性
选择匹配您 Medusa 后端版本的插件版本 :
| 美杜莎版本 | 插件版本 | 安装命令 |
|---|---|---|
>= 2.13.* | latest | npm install @alphabite/medusa-paypal |
< 2.13.* | 0.2.5 | npm install @alphabite/[email protected] |
说明
- 美杜莎2.13.*及以上: 安装插件的最新版本 。 这是积极维护的放出,并与最新的美杜莎API相容需要.
- 2.13.*以下为美杜莎: 将插件绑入版本
0.2.5. 后期插件版本依赖美杜莎2.13中引入的API,不会对更古老的后端工作.
在安装前, 请验证您的美杜莎版本 :
npm list @medusajs/medusa
然后安装匹配插件版本 :
# Medusa >= 2.13.* (latest)
npm install @alphabite/medusa-paypal
# Medusa < 2.13.* (pinned)
npm install @alphabite/[email protected]
QQ 在本地、 中继和生产中使用相同的插件版本, 以避免运行时间出错 .
美杜莎 PayPal 插件
Alphabite PayPal 插件将 PayPal 支付处理整合到您的美杜莎商店中 。 它处理各种付款流程,包括收取付款、管理退款以及确保有力的错误处理.
目录
* 核心特征
- QQ 无缝支付整合
- 处理各种 PayPal 错误状态
- ++ 支持直接从美杜莎管理员处退款
- QQ 在同一支付意图范围内为每次支付尝试创建新订单ID
- * 选择性地将货运和客户数据纳入PayPal订单
兼容性
- 后端 : 美杜莎 v2+ (英语)
- 前端 : 框架不可知性( 包含 PayPal 的 SDK)
- 管理员 : 退款功能并入美杜莎行政
常见案件
- 接受对产品和服务的付款
- 有效管理付款和退款
- 确保以全面处理错误的方式进行稳健的付款处理
页:1
完整文件请访问 PayPal 插件文档。 。 。 .
* 安装
这个向导在您的美杜莎后端安装和配置 Alphabite PayPal 插件 .
1. 安装插件
通过 npm 安装软件包 :
npm install @alphabite/medusa-paypal
2. 登记插件
将插件添加到您的 medusa.config.ts 或者说 medusa-config.js数字 :
{
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项目兼容
下一个步骤
👉 配置指南 👉 加入我们的Discord社区 用于更快的支持
QQ 前端集成
本指南解释如何将 PayPal 支付流量整合到您的 Next.js storefront 中使用 @paypal/react-paypal-js。 。 。 .
1. 安装附属设施
安装 PayPal 官方反应 SDK :
npm install @paypal/react-paypal-js
2. 环境变量
请确保您在您的环境变量中提供公共 PayPal 客户端标识 :
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数字 :
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. 付款流程详情
- 客户端托肯时间轴: 必须 从您的 Medusa 后端获取客户端符号( Name
/store/paypal/client-token并传递给PayPalScriptProvider。这授权客户端代表您的账户采取行动. - 创建顺序编号:
createOrder当用户试图支付时会触发回调。 它应该在美杜莎启动付款会话,并归还支付保单的身份证. - 核准编号:
onApprove在 PayPal 成功授权支付后恢复调用 。 使用此来完成美杜莎语中的顺序( 如,placeOrder) (中文(简体) ).