Medusa 移动支付实战支付宝、微信支付集成从看懂到动手【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa这篇文章写给想在 Medusa 店铺里接入支付宝、微信支付等移动支付方式的新手开发者。它会用一条完整的学习路径带你摸清支付模块的组织方式、支付提供商该怎么开发、配置文件怎么写、上线前要避开哪些坑——读完你就能照着动手不用干等官方出插件。一、先看清底牌支付体系到底是怎么组织的这一节的目标是让你在几分钟内找到所有支付相关代码的位置知道自己的插件该写在哪里、该改哪里。Medusa 把支付能力拆成了两层各管一摊支付核心模块packages/modules/payment/负责支付集合、支付会话、退款、捕获这些业务数据的存取核心逻辑在src/services/payment-module.ts和src/services/payment-provider.ts两个文件里。在src/models/下你能看到payment-collection.ts、payment-session.ts、refund.ts、capture.ts等模型它们对应了支付业务里最基础的几张数据表。支付提供商packages/modules/providers/真正跟支付宝、微信支付、Stripe 这些第三方平台打交道的翻译官负责把各家五花八门的 API 翻译成 Medusa 统一的方法调用。一句话记住模块管账提供商管钱。要接一种新的支付方式90% 的工作量都落在提供商这一层核心模块几乎不用动。而最值得你参考的样例就是项目里现成的 Stripe 实现位于packages/modules/providers/payment-stripe/目录下面所有代码示例都以它为准。二、动手前必须想明白的四个问题这一节不写代码但比写代码更重要——这四个问题想通了实现时你不会迷路。① 支付会话从哪来、谁负责它用户发起支付时系统会为这笔订单创建一个支付会话对应payment-session.ts模型会话里记录当前处于什么状态。提供商要做的事就是把这个会话的生命周期待支付、已授权、已捕获、失败、退款映射到 Medusa 的状态枚举上。② 异步通知怎么接支付宝、微信支付都是异步玩法用户付完钱平台不是等你来查而是主动回调你的服务器。这条链路必须打通否则会出现用户钱扣了、订单还挂着的事故。Stripe 里对应getWebhookActionAndData这类方法回调后要把订单状态同步更新。③ 授权和捕获是两回事预授权模式下先冻结资金authorize发货后再真正扣款capture。这能防止钱没收到货先发了。你的提供商要根据业务需要决定支持哪种模式并在配置里显式声明。④ 退款、部分退款要不要支持电商退货是常态。至少要支持全额退款部分退款则看支付平台 API 能力能支持就尽量支持别把退货流程卡死。三、照葫芦画瓢手写一个支付宝提供商这一节带你实操。核心思路是继承框架提供的AbstractPaymentProvider把支付宝的接口填进约定好的方法里。先看一眼 Stripe 是怎么干的packages/modules/providers/payment-stripe/src/services/stripe-provider.ts这个文件本身很短它只是声明自己的标识符identifier并继承core/stripe-base.ts真正的逻辑都写在stripe-base.ts的各个方法里例如initiatePayment、authorizePayment、getPaymentStatus、refundPayment、getWebhookActionAndData。照着这个套路支付宝提供商可以这样搭骨架import { AbstractPaymentProvider } from medusajs/framework/utils class AlipayProviderService extends AbstractPaymentProviderAlipayOptions { // 全局唯一的提供商标识注册和配置时都要用 static identifier pp_alipay constructor(cradle, options) { super(...arguments) // 在这里初始化支付宝 SDK比如把 appId、私钥传进去 } async initiatePayment(input) { // 1. 拿 input 里的金额、订单号去调用支付宝下单接口 // 2. 取回平台生成的交易号、跳转链接或二维码内容 // 3. 把结果放进 data 里返回给 Medusa 存储 return { data: { tradeNo, qrCodeUrl } } } async getPaymentStatus(input) { // 查询支付宝订单状态翻译成 Medusa 认识的支付状态 } async refundPayment(input) { // 调用支付宝退款接口返回退款是否成功 } } export default AlipayProviderService每个方法都有明确的入参和出参约定照着stripe-base.ts逐个对照着抄出错概率会低很多。金额注意用最小单位传递避免浮点数精度问题——Stripe 实现里专门写了utils/get-smallest-unit.ts处理这件事你的提供商也要这样干。四、把提供商装进系统注册与配置这一节讲怎么让 Medusa 认识你刚写的提供商。在medusa-config.js里找到支付模块的配置区把提供商挂进providers数组。参考项目里的integration-tests/http/medusa-config.js写法是这样的const { defineConfig, Modules } require(medusajs/utils) module.exports defineConfig({ modules: { [Modules.PAYMENT]: { resolve: medusajs/payment, options: { providers: [ { resolve: ./src/modules/alipay, // 你的提供商入口 id: pp_alipay, // 与 identifier 保持一致 options: { appId: 你的支付宝AppID, privateKey: 你的应用私钥, alipayPublicKey: 支付宝公钥, }, }, ], // 这两个选项控制 webhook 重试测试时可以调成 0 webhook_delay: 0, webhook_retries: 0, }, }, }, })resolve指向提供商代码id是全局唯一标识options里放密钥这类敏感配置。密钥千万别硬编码进代码仓库用环境变量注入更稳妥。注册完成后重启服务店铺后台的支付方式列表里就会出现支付宝选项可以直接拿来创建支付会话。五、微信支付的特别之处这一节讲清楚微信支付和支付宝的差异点帮你少走弯路。微信支付没有统一的下单接口而是按场景拆成 JSAPI公众号内、小程序支付、APP 支付、H5 支付等好几种每种场景要求的参数都不一样。实现时建议先锁定一个场景比如小程序跑通后再横向扩展。另外三点要注意签名与证书微信支付用 APIv3 密钥加证书双向验证证书路径要配进 options别放进代码里。统一下单的 openidJSAPI 和小程序支付都依赖用户的 openid这意味着你的前端要配合做授权登录不能只靠后端。回调验签微信的回调通知也需要验签后才能采信否则很容易被伪造请求干扰订单状态。好在这些差异都被封装在提供商这一层你只需要保证对外暴露的方法符合 Medusa 约定微信和支付宝的差异不会污染到核心模块。六、上线前先过一遍踩坑清单这一节是实战经验浓缩条条都是真实踩过的坑。金额单位换算第三方平台通常收最小货币单位分/厘Medusa 内部有自己的金额口径两边不一致会出现少收 100 倍钱的严重事故务必像 Stripe 实现那样做专门的单位换算。webhook 秘钥不配Stripe 源码里专门警告过不配webhookSecret会导致验签失败、订单永远停留在待处理状态。支付宝、微信同理回调签名验证必须配齐。回调幂等支付平台可能重试回调处理逻辑要保证同一笔订单被回调多次结果一致。测试环境与生产环境隔离密钥、证书、回调地址都要分开千万别把测试环境的配置带到生产。日志要完整每笔支付从发起到回调全程留痕出问题才能对账定位最好把平台返回的原始报文也存下来。七、从沙箱到生产分步推进的路线图这一节给你一条可执行的上线路线避免一把梭。沙箱验证用支付宝/微信支付的沙箱环境跑通下单 → 支付 → 回调 → 订单更新 → 退款全流程确认状态流转正确。小范围试点先放一个低价商品或一个测试店铺试跑一周观察支付成功率、回调延迟、退款耗时。监控告警至少盯住三个指标——支付失败率、回调积压数、退款失败数任一异常立即告警。回滚方案支付插件要能一键停用并切回备用支付方式别让支付故障拖垮整个店铺。下一步动手吧回头看Medusa 的移动支付接入其实就三步看懂packages/modules/payment/的模块结构照着payment-stripe的实现写自己的提供商再把插件注册进medusa-config.js。这套架构把复杂的支付差异收敛在提供商一层让新增支付方式变成一件可以量化的工程任务。建议你先在一个小业务场景里试跑支付宝集成验证通过后再扩展到微信支付和全量推广同时保持对平台政策和技术更新的关注确保支付服务长期稳定。现在就去packages/modules/providers/payment-stripe/src/core/stripe-base.ts翻一翻源码从读懂它开始你的第一个支付提供商已经在路上了。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考