在 Medusa 中接入支付宝、微信：移动端支付从 0 到上线的完整路径

在 Medusa 中接入支付宝、微信移动端支付从 0 到上线的完整路径【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa想给 Medusa 开源电商接上支付宝、微信这类移动端支付这篇文章按一次真实集成的顺序讲Medusa 的支付模块怎么分层、照 Stripe 的现成骨架改出支付宝 Provider 只需两步、微信和支付宝在签名与回调上的实际差异、沙箱里如何跑通一笔订单最后是上线前该逐项打勾的清单。 支付模块分层payment 管账本providers 管渠道Medusa 把支付拆成两层理解这一点后面就顺了。一层是支付模块packages/modules/payment/它是账本负责支付会话一次向渠道发起的收款过程、支付记录、捕获和退款这些实体以及它们的数据库模型和服务逻辑。它不关心你收的是卡还是扫码只关心这笔钱的状态是什么。另一层是提供商目录packages/modules/providers/里面每个子包是一个具体渠道的实现比如 Stripe 参考实现在 packages/modules/providers/payment-stripe/。Provider 只负责跟渠道的 API 打交道创建收款单、验签回调、发起退款。两层之间靠注册机制接起来。payment 模块启动时有一个 Provider 加载器源码在 payment 模块的src/loaders/providers.ts它做两件事把你配置里的 Provider 类实例化后挂进依赖容器再把它写进数据库并标记为启用——所以新 Provider 一注册后台管理界面里就会自动出现不需要写任何管理端代码。 照着 Stripe 改出支付宝 Provider复用骨架 注册 2 步2.1 复用 Stripe 的骨架打开 Stripe 的实现你会发现结构很干净core/stripe-base.ts是一个抽象基类把initiatePayment、getPaymentStatus、refundPayment、validateWebhook这些接口方法都实现了具体 Provider 类比如services/stripe-provider.ts只有十几行主要是声明自己的标识符。做支付宝就照这个模式复制新建payment-alipay目录建一个alipay-base.ts基类继承框架的AbstractPaymentProvider把 Stripe 基类里的方法名一一对应替换initiatePayment里调支付宝的创建收款接口沙箱期可以先返回测试用的支付 URLvalidateWebhook里换成支付宝的 RSA 验签refundPayment里调退款接口金额注意按最小货币单位换算——支付宝接口用的是分的概念Stripe 基类里专门有个get-smallest-unit工具函数干这个事可以借鉴它的思路。2.2 注册 2 步配置文件 后台启用代码放好后接入只做两步。第一步在项目配置文件里声明 Provider// medusa-config.jspayment 模块配置节选 modules: [ { key: payment, resolve: medusajs/payment, options: { providers: [ { resolve: ./src/providers/payment-alipay, id: alipay }, ], }, }, ]第二步重启服务后到后台 Settings 里把 Alipay 这个 Provider 启用。加载器会自动完成数据库登记订单里就能选它了。注意一个细节id字段用来区分同一渠道的多个实例比如支付宝个人版和企业版可以注册成alipay和alipay_biz两个实例互不干扰。⚖️ 微信支付 vs 支付宝回调、签名、退款差在哪两个渠道接入骨架相同差别在四个地方对照着做即可维度支付宝微信支付签名体系RSA2 非对称配置 AppID 应用私钥 支付宝公钥APIv3 用平台证书 API 密钥证书需要定期轮换回调验签拿响应里的sign字段用支付宝公钥验要用Wechatpay-Signature等请求头现场计算验签且回调报文是 AES 加密的要先解密再读退款调退款接口按原交易号退支持部分退款退款走独立接口且异步提交后还要等微信的退款结果通知才算完成多端场景一套接口 场景参数区分App / H5 / 小程序JSAPI、小程序、App、H5 是四个独立接口openid这类前置参数各自不同其中微信回调先验签、再解密、后读内容这三步最容易踩坑Stripe 基类里validateWebhook是单个方法你可以把三步都放进去但要保证验签失败时直接丢弃、不返回成功否则会被恶意重放。 沙箱下单到对账把一笔支付真正跑通跑通的三个环节① 沙箱下单。支付宝和微信都提供沙箱支付宝给测试买家账号和测试 AppID微信给沙箱商户号。先在 Medusa 里下一单确认选中的支付方式是alipay下单接口能返回 Provider 给的支付数据一个跳转 URL 或拉起参数就算通了第一步。② 异步回调。用户在沙箱里付完渠道服务器会 POST 到你的 webhook 地址。建议本地先用 ngrok 之类的内网穿透把回调指到开发机验证三件事validateWebhook验签通过、支付会话状态从 pending 变成 succeeded、订单状态跟着变成 paid。回调查不到时优先看 Provider 日志里的验签结果而不是怀疑网络。③ 主动对账。回调可能迟到或丢失所以上线前要让定时查渠道侧交易状态这条兜底路径也工作——对应 Provider 的getPaymentStatus方法。跑一批沙箱订单故意漏掉其中一笔的回调确认主动查询能把状态补齐这笔支付才算真正跑通。✅ 上线前的安全与体验清单webhook 验签开启且失败时返回非 2xx杜绝伪造回调回调处理做幂等同一笔支付重复通知时直接返回成功不重复落状态私钥、APIv3 密钥只放环境变量或密钥管理不进代码仓库微信 API 平台证书轮换流程已演练建议每 30 天内检查到期时间主动查询兜底任务已部署覆盖回调丢失场景支付失败时前端有明确的错误提示文案而不是裸的报错码退款走原渠道原交易号退款结果同样依赖异步通知时已处理上线后首周盯住两件事支付成功率、回调到达延迟建议先在沙箱把上面的清单全部打勾再切一个低客单价的真实商品做一笔小金额生产验证最后全量放开。移动端支付的核心不在接上而在回调链路每一环都可验证——把这条链路在沙箱里跑透生产环境要担心的就只剩下渠道侧的稳定性了。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考