Medusa 移动支付集成踩坑复盘客户付了款你的订单却不见了【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa深夜 11 点客户发来一条语音扫码付了 328 元页面明明显示支付成功可店铺后台翻遍了订单列表也找不到这笔单。你查了一下账户钱确实进来了但货发不出去钱也没法退。这不是段子是很多人第一次做 Medusa 移动支付集成时真实遇到的事故。这篇文章就以这次翻车为线索带你把 Medusa 的支付模块拆开揉碎讲清楚钱从哪儿进来、订单为什么会凭空消失以及怎样照着项目里现成的参考答案用最短路径把支付宝、微信这类移动支付真正跑通少踩签名、回调、金额单位这些隐形地雷。先复盘事故钱进来了订单却消失了那天的情况大概是这样的你照着网上零散的教程写了支付请求用户扫码付款后支付平台确实返回了成功于是代码里return success就收工了。结果后台一查订单状态还停留在待支付工作流根本没往下走。问题不在请求这一半而在你压根没听支付平台的回话。移动支付是异步的你发起支付、用户付款之后平台不会立刻在你那条请求里告诉你结果而是过一会儿主动敲你的门也就是回调/异步通知把这笔钱真的到账了的消息送过来。你没装这扇门等于店家永远收不到到账通知自然也就不会发货。后台的订单、客户、库存都在这个入口里管理但前提是支付环节先把订单喂到正确的状态机里。第一层拆解你把收钱当成了支付的全部很多人下意识觉得支付就是一台取款机——投币、出钱、完事。但移动支付更像一场对暗号的双人舞它有完整的生命周期任何一个环节断了订单都会卡在半路支付动作大白话解释放在支付宝/微信里对应哪一步发起支付把付款二维码递到用户面前统一下单、生成二维码/跳转链接支付回调用户付完后平台主动来报信异步通知你钱到了授权/捕获确认到账、真正锁定这笔钱商家确认收款、资金结算查询状态随时查某笔单现在啥情况订单查询接口退款把钱原路退给用户退款接口你只做了发起支付就以为大功告成后面的回调、捕获全没接订单自然停在原地。支付不是一次请求而是一串状态流转。第二层拆解回调这扇门到底该怎么装再打个比方线下吃饭扫码付款店家不会盯着你的手机屏幕看而是等柜台那个收款小喇叭响一声才让后厨动火。那个小喇叭就是支付平台的异步回调。在 Medusa 里支付模块专门留了处理回调的通道还带了webhook_delay回调延迟和webhook_retries回调重试次数这样的配置项——平台推一次没收到还会重推你得保证每次都能稳稳接住、且同一个消息重复推过来时不会重复处理这就是幂等。所以正确姿势是发起支付只管把支付链接交给用户用户付完靠回调把订单从待支付推进到已支付然后再触发发货工作流。顺序错了或者少了任何一环就是钱到了、货没发的经典事故。先看懂 Medusa 的插座与插头设计动手之前用一分钟理解 Medusa 支付系统长什么样。它的设计非常像一个电源排插插座packages/modules/payment/这个支付模块它不关心你用的是支付宝还是微信只定义一套通用动作发起、查询、捕获、退款、回调。插头packages/modules/providers/payment-stripe/目录下的 Stripe 供应商就是官方做好的一只插头。它是你的参考答案——想接支付宝就照着这只插头的形状做一只新的插到同一个插座上。项目里每个支付供应商都要实现一套固定的动作上面表格里那几行Medusa 才能指挥它干活。你不用从零发明协议抄 Stripe 这只插头的作业就行核心逻辑是自己的支付 SDK 负责和支付宝/微信对话Medusa 的通用动作负责翻译成订单状态。从零接一个移动支付供应商四步就够第一步建目录、抄作业。在packages/modules/providers/下新建payment-alipay/或payment-wechat/把 Stripe 插头的目录结构照搬过来把 Stripe SDK 换成对应支付平台的 SDK。第二步把动作填上。重点实现发起支付、回调处理、查询状态、退款这四件套。注意金额统一用最小货币单位分/分避免浮点误差——这是 Stripe 插头里专门封装了getSmallestUnit这类工具的原因。第三步把插头插进插座。在项目的medusa-config.js里把新供应商注册进支付模块modules: { [Modules.PAYMENT]: { resolve: medusajs/payment, options: { providers: [ { resolve: medusajs/payment-alipay, options: { appId: 你的支付宝AppID, privateKey: 你的商户私钥, alipayPublicKey: 支付宝公钥, webhookSecret: 回调验签密钥, }, }, ], }, }, }密钥别写死在代码里用环境变量注入这是支付安全的基本功。第四步配回调地址开门迎客。在支付宝/微信开放平台后台把回调地址填成你 Medusa 服务提供的回调路由保证公网能访问到。然后到沙箱环境里跑一遍付款 → 回调 → 订单变已支付 → 发货的完整链路。最容易翻车的 6 个现场附前后对照① 签名校验永远失败。支付宝/微信的签名对参数的拼接顺序、编码、换行都极其敏感多一个空格都过不去。修法用平台官方的 SDK 生成签名别自己手搓字符串拼接然后先打印原始串和官方示例逐字符对比。② 金额单位搞混。用户在 App 里看到的是328.00 元支付平台接口要的是32800 分。你传了328顾客会惊喜地发现自己只用 3 块 2 毛 8 买了个包。修法进支付模块前统一换算成最小单位入库、出库全程一致。③ 回调重复处理。支付平台可能把同一个到账通知推两三次网络抖动也会触发重试。如果你每次都把订单再已支付一遍库存就减了两次。修法回调处理做成幂等处理前先查订单当前状态已处理过就直接返回成功。④ 回调地址配成了内网地址。平台敲门敲了个寂寞。修法回调地址必须是公网可达的 HTTPS 地址本地联调可以用内网穿透工具上线前再换成正式域名。⑤ 沙箱密钥和生产密钥混用。拿沙箱公钥去验生产的签名验一次崩一次。修法环境严格隔离配置里区分沙箱/生产两套密钥靠环境变量切换。⑥ 退款时资金状态不对。想退款但钱还挂在未捕获状态平台直接拒绝。修法先走捕获流程把资金锁定再做退款顺序别反。上线前最后一关让支付流程跑在多环境隔离的云跑道上支付不是写完就能撒手的它最怕测试好好的、上线就崩。Medusa 官方的部署思路是把开发/预览环境和生产环境严格隔开你在预览环境里随便用沙箱账号试付验证通过后才部署到生产两边数据、密钥、回调地址互不干扰。上线后再补两件事一是监控告警支付失败率一旦抬头就立刻报警二是对账每天拉支付平台的流水和本地支付记录比对一遍多了少了都查得出——Medusa 的支付模块本身就记录了每一笔支付、退款、捕获的明细对账时直接拿来用即可。交付自检清单照着打勾再上线发起支付能生成支付链接/二维码用户能正常完成付款回调地址公网可达收到通知后订单能从待支付变成已支付同一回调重复推送不会重复处理幂等已验证金额全程使用最小单位与支付平台返回的金额一致签名验签通过密钥走环境变量未提交到代码仓库沙箱完整跑通付款→到账→发货和退款两条链路生产环境与预览环境配置完全隔离回调域名已切换已设置支付失败监控告警并确认日志里能查到每笔支付流水接下来你可以动手了先别急着写支付宝的对接代码。建议你按这个顺序走一遍把仓库 clone 下来git clone https://gitcode.com/GitHub_Trending/me/medusa打开packages/modules/payment/读一遍支付模块的目录结构再翻翻packages/modules/providers/payment-stripe/里 Stripe 插头是怎么实现那些动作的然后拿沙箱环境做第一个最小可支付Demo——先跑通一笔再考虑接第二种支付方式。等你把第一笔支付完整跑通、订单稳稳变成已支付再回头看今晚那次客诉你会笑着感叹原来移动支付集成难的不是代码而是搞懂那扇异步回调的门。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考