Medusa 移动端支付集成指南支付宝与微信支付接入的完整路径【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa如果你的电商系统跑在 Medusa 上正准备接入支付宝、微信支付这类移动端支付这篇文章会带你走一遍从准备商户资料到沙箱验证的完整流程。内容适合两类读者刚接触 Medusa 支付集成的新手开发者以及需要评估接入工作量、制定上线计划的技术负责人。全文不依赖任何支付平台的具体代码实现重点讲清楚每一步用户做什么、系统对应什么具体字段与接口行为请以对应支付平台最新文档和仓库中的现有实现为准。先看模块结构Medusa 支付系统长什么样动手之前先花几分钟了解代码放在哪里后面所有工作都有依托。支付核心模块位于 packages/modules/payment/。其中src/services/payment-provider.ts负责按 ID 找到已注册的支付提供商并转发调用创建会话、查询状态、授权、捕获、取消、退款src/services/payment-module.ts承载订单层面的支付业务逻辑。数据模型在src/models/下包括支付会话payment-session、支付记录payment、捕获capture、退款refund等。做对账时这些模型就是系统侧的账本。可参考的提供商实现是 packages/modules/providers/payment-stripe/。它的src/core/stripe-base.ts演示了一个提供商需要实现的能力initiatePayment发起支付、getPaymentStatus查询状态、refundPayment退款、webhook 事件校验以及请求时携带幂等键idempotency key的做法。提供商接口的定义在 packages/core/types/src/payment/provider.ts里面还定义了系统识别的标准状态authorized、captured、pending、failed、canceled等。你的支付宝、微信实现最终都要映射到这套状态上。支付宝、微信目前不在仓库内置的提供商列表里需要作为自定义模块编写。好消息是接口边界是现成的照着 Stripe 实现的结构去写即可。接入支付宝前需要准备哪些信息Medusa 如何接入支付宝第一步不在代码里而在商户后台。按顺序准备开放平台账号在支付宝开放平台创建或确认应用拿到 AppID。密钥对生成应用私钥并把应用公钥提交给支付宝同时保存支付宝公钥用于校验回调签名。接口权限开通当面付 / 手机网站支付 / APP 支付中你实际要用的产品不同产品对应不同的下单接口。沙箱账号申请沙箱环境拿到沙箱的 AppID 和密钥。沙箱与生产是两套完全不同的配置不要混用。回调地址准备一个公网可访问、走 HTTPS 的 URL用于接收支付宝的异步通知。这些信息的存放位置建议统一走环境变量或配置中心的加密项写进medusa-config里交给提供商模块读取。典型的配置字段包括appId、应用私钥、支付宝公钥、网关地址沙箱/生产各一个、回调地址。Medusa 支付宝支付配置与接口实现实现支付宝提供商时对照IPaymentProvider接口逐项落地创建支付会话用户在前端提交订单后Medusa 会调用你的initiatePayment。这里调用支付宝的下单接口如 trade_create / trade_page 对应场景把返回的trade_no作为会话 ID 存下来并附带上幂等键避免网络重试时产生两笔订单。金额换算支付宝以分为单位计费而 Medusa 传递的金额是数字型分值。Stripe 实现里用getSmallestUnit做币种换算你可以借鉴同样的思路先查清币种精度再落单这是新手最容易踩的坑。状态查询getPaymentStatus里调用支付宝的查单接口把WAIT_BUYER_PAY、TRADE_SUCCESS、TRADE_CLOSED等状态翻译成 Medusa 的标准状态pending、captured、canceled。退款refundPayment调用退款接口支持全额和部分退款注意退款金额不得超过原交易金额。webhook实现一个校验签名的 webhook 入口。Stripe 的做法是配置里必须提供webhookSecret否则依赖回调的流程如 3D 验证后的状态回写会卡在 pending支付宝侧等价动作是用支付宝公钥验签验签失败的请求直接丢弃并记录日志。配置示例结构示意字段名以你的实现为准// medusa-config 中注册自定义支付提供商 modules: { payment: { providers: [ { resolve: ./src/payment-alipay, options: { appId: process.env.ALIPAY_APP_ID, ... } } ] } }Medusa 微信支付配置不同场景的差异Medusa 微信支付集成的思路与支付宝相同差异主要在用户从哪里付钱。微信的几种场景要分开实现场景用户在哪里关键输入JSAPI 支付微信内 H5 页面用户 openid小程序支付小程序内小程序 appid openidAPP 支付独立 APP 内预支付交易号H5 支付微信外的手机浏览器跳转链接配置上比支付宝多几项商户号mchId、API 证书用于 APIv3 签名与回调解密、APIv3 密钥。建议按场景拆分成独立的支付会话类型让前端根据运行环境选择走哪条链路而不是在一个入口里堆 if-else。回调处理上微信 APIv3 的回调是加密的先验签再用 APIv3 密钥解密 payload然后才进入和支付宝一样的更新会话状态 → 推进订单流程。解密前的任何字段都不要信任。支付回调如何处理幂等、重试与异常回调是支付结果的主通道但设计上要假设回调可能重复、可能迟到、可能丢失。幂等同一笔支付的成功通知可能送达多次。处理前先查当前会话状态已经是captured就直接返回成功不做二次推进。Stripe 实现中所有带写操作的方法都传了idempotencyKey你可以把同样的习惯用在调微信/支付宝接口上。查询兜底回调丢失时订单会停留在 pending。为这类订单加一个定时任务周期性调用getPaymentStatus主动向平台查单查到成功再补推订单。这是保证钱到了、单没成这类事故的最后一道防线。失败重试查单和推进订单的调用要带超时与退避重试重试仍然失败的落库为异常记录并告警转人工处理而不是无限重试。异常场景验签失败丢弃并记录原始报文、金额与系统订单不一致拒绝并告警绝不放行、状态回退已捕获又收到关闭通知以平台最新查单结果为准。支付退款与对账要注意什么Medusa 支付退款与对账涉及两套数据系统侧的退款模型packages/modules/payment/src/models/refund.ts和平台侧的退款/交易流水。退款留痕每次调用退款接口后保存平台返回的退款单号与状态。部分退款多次发生时累计退款金额必须 ≤ 原支付金额在代码里做硬性校验。退款状态异步性支付宝、微信的退款都不是同步到账退款单有处理中状态。系统侧要能表达退款已发起、未完成完成靠退款通知或轮询查单确认。对账口径对账文件以平台流水为准和系统的 payment 记录按平台交易号关联而不是只按订单号。重点核对三类差异平台成功但系统 pending回调丢失、系统成功但平台查不到严重异常、金额或币种不一致。对不上时的动作差异单先隔离、再人工确认、最后用调账或补推订单收口全程留操作记录。上线前检查清单沙箱全部跑通后按这张清单逐项打勾再切生产沙箱环境完整走一遍下单 → 支付 → 回调 → 订单状态变化 → 全额退款 → 部分退款验签失败、金额不符两类恶意/异常回调的测试用例有通过记录回调 URL 为 HTTPS且公网可达证书有效期已确认生产与沙箱的 AppID、密钥、网关地址分开管理切换不会串环境日志里能按交易号检索到完整链路下单、回调、退款监控已就位支付成功率、回调失败率、pending 订单超龄数量有回滚预案新提供商出问题时可以把它从配置中摘除订单回落到原有支付渠道下一步把支付宝或微信中的一个先做出来在沙箱里跑通支付 退款两条链路第二个渠道的接入成本会显著降低。实现细节上拿不准的地方直接对照 packages/modules/providers/payment-stripe/ 的现有代码接口行为最终以支付平台最新文档为准。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考