简介这套基于PHP的PaySDK支付接口集成设计源码面向需要为Web应用接入支付宝、微信支付等主流支付通道的PHP开发者。项目运行于PHP 5.4及以上环境使用PHP完成支付接口调用、服务商交互、数据处理与用户身份验证等核心逻辑并配合HTML构建简洁的交互界面。压缩包共173个文件其中170个为PHP源码另含txt说明、license许可与composer.json依赖配置整体仅312KB结构紧凑。目前已有270人学习下载适合正在开发电商、会员充值或内容付费系统的初中级开发者借鉴。源码配套宇润PHP全家桶技术交流群目录划分清晰便于按模块查看业务参数封装、证书下载与签名验证等实现composer.json可快速还原运行环境readme与许可证文件也降低了上手门槛。需要留意的是该项目已转为社区维护模式不再更新日志建议使用者同步关注GitHub上的最新动态。1. PaySDK 是什么支付接口集成这件事为什么值得为它单独维护一套源码做过支付接入的 PHP 工程师多半有这样的经历微信支付刚调通产品经理说下个月上支付宝。你打开老代码一看微信那边是拼 XML 报文、MD5 签名、金额单位是分支付宝则是 JSON 请求、RSA2 签名、金额单位是元。业务逻辑几乎不能复用代码里开始出现if ($channel wechat)这种分支越堆越乱。基于 PHP 的 PaySDK 支付接口集成设计源码解决的就是这个问题它用统一的门面入口把微信、支付宝各渠道的参数组织、签名计算、回调验签全部封装进各自的渠道适配器里。业务层只调用支付、退款、查询、通知这几个固定方法不再关心对方接的是什么协议。适合两类人一是 PHP 项目要接两个以上支付渠道的二是想把这套集成交给新同事而不至于让他翻车三天的团队。2. 装库与初始化先看懂 PaySDK 的组合模式设计再写第一行业务代码2.1 为什么是组合而不是继承渠道之间的差异远大于共性我在给团队做技术方案时经常被问到一个问题微信支付和支付宝支付都是支付为什么不抽一个BasePay父类让两个渠道去继承这个思路听着合理落地就变味。微信支付和支付宝的差异不只是签名算法不同。微信统一下单要传openid、trade_type返回的是 XML支付宝当面付要传product_code、qr_pay_mode返回的是 JSON。更麻烦的是两者的异步通知格式、验签数据源、应答报文完全不同。如果强行抽父类你会发现这个父类除了pay()、refund()这几个空方法名之外什么都没法写——每个方法的入参、返回、异常处理在不同渠道里长着不同的样子。继承在这里制造的是耦合不是复用。PaySDK 的主流做法是组合。主入口类PaySDK持有一组渠道实例每个渠道实例各自实现签名、请求、验签的逻辑。业务代码拿到的永远是同一个对象、同一套方法名至于内部是拼 XML 还是拼 JSON是业务层不需要关心的事。这种结构对后续扩展尤其友好接一个新渠道就是新写一个实现了统一接口的类不用动任何老代码。2.2 composer 安装与初始化最小可跑通的配置长什么样安装用 composer 单条命令就能完成不需要手工下载源码包。安装完成后第一个要做的不是写下单逻辑而是写初始化。我会先建一个PayConfig.php之类的配置文件把微信和支付宝的密钥集中管理。// config/paysdk.php return [ default wechat, channels [ wechat [ app_id wx1234567890abcdef, mch_id 1900000101, key 商户APIv3密钥, cert_path storage_path(certs/apiclient_cert.pem), key_path storage_path(certs/apiclient_key.pem), notify_url https://api.example.com/pay/notify/wechat, ], alipay [ app_id 2021003123456789, private_key 应用私钥字符串或文件路径, public_key 支付宝公钥字符串, notify_url https://api.example.com/pay/notify/alipay, ], ], ];接着初始化主入口use PaySDK\PaySDK; $config require config/paysdk.php; $pay new PaySDK($config); // 切换渠道$pay-channel(alipay) 或 $pay-channel(wechat)这段代码的逻辑是把渠道配置集中在一个数组里主入口根据channel()传入的名字加载对应适配器。new PaySDK($config)本身不发起任何网络请求它只做配置装载和渠道实例化所以放在框架的启动阶段没有性能负担。storage_path(certs/...)这类写法在 Laravel 之外要用__DIR__ . /certs/...代替目的是让证书路径不依赖当前工作目录。2.3 初始化阶段最容易埋雷的三个配置项第一个雷微信的证书路径。很多人直接写cert_path ./cert/apiclient_cert.pem本地跑得好好的部署到服务器上就报错找不到证书。原因很简单——PHP 的当前工作目录在不同运行方式下不一样CLI 和 FPM 拿到的路径可能不同。我一般会强制要求配置项写绝对路径或者在初始化时用realpath()校验一遍文件不存在直接抛异常而不是等到请求微信时才报一个莫名其妙的curl error 58。第二个雷回调地址。微信和支付宝的异步通知要求公网可访问本地开发时用内网穿透临时顶一下没问题但不要把内网穿透的临时域名写进生产配置。通知地址一旦在商户平台配置错了商户后台可以改但代码里的notify_url是随支付订单提交的旧订单永远会回调到错误地址这种问题只能等订单超时。第三个雷签名方式。微信支付现在推荐 HMAC-SHA256旧代码里可能还是 MD5支付宝默认 RSA2SHA256WithRSA。初始化配置里如果没有显式声明签名类型SDK 会有默认值但这个默认值未必和你商户平台上的设置一致。我在接入时一定会在配置里把签名方式写死避免 SDK 升级后默认值变化导致全线签名失败。3. 微信支付接口下单与支付宝支付接口下单渠道差异在 SDK 里如何被抹平3.1 微信 JSAPI 下单openid、分单位金额、先查用户再下单微信支付接口里JSAPI 下单需要用户openid所以业务流程通常是前端拿到code后端用code换openid再用openid去下单。PaySDK 把统一下单封装成了pay()方法业务层只需要组装订单参数。// 微信 JSAPI 下单 $order [ out_trade_no date(YmdHis) . mt_rand(1000, 9999), total_fee 1, // 注意微信单位是分1 0.01元 body 商品描述, openid $userOpenId, trade_type JSAPI, ]; $result $pay-channel(wechat)-pay($order); // $result 里拿到 prepay_id 后前端需要再组一次签名 if ($result[code] SUCCESS) { $prepayId $result[data][prepay_id]; // 用 prepay_id 生成 JSAPI 所需参数 $jsapiParams $pay-channel(wechat)-buildJsapiParams($prepayId); }这里的out_trade_no是商户订单号微信要求 32 个字符以内我用时间戳加随机数拼一个是习惯做法但要保证在数据库里有唯一索引兜底。total_fee的值单位是分这是微信支付接口集成中最大的一个坑很多新手在这里把 0.01 元写成0.01结果微信拒单提示金额无效。buildJsapiParams()返回的数组包含appId、timeStamp、nonceStr、package、signType等字段前端wx.chooseWXPay直接用。3.2 支付宝当面付与 PC 下单金额单位是元参数名完全不同支付宝的参数风格和微信差异很明显最典型的就是金额字段微信叫total_fee、单位分支付宝叫total_amount、单位元而且要求字符串类型。同样一顿操作PaySDK 的调用形式不变只是业务层组装的参数不同。// 支付宝当面付扫码枪 / 商家扫码 $order [ out_trade_no date(YmdHis) . mt_rand(1000, 9999), total_amount 0.01, // 字符串单位元 subject 商品描述, product_code FACE_TO_FACE_PAYMENT, ]; $result $pay-channel(alipay)-pay($order); // PC 网站支付product_code 换成 FAST_INSTANT_TRADE_PAY返回的是跳转HTML if ($result[code] 10000) { echo $result[data][body]; // 直接输出这段HTML浏览器会跳到支付宝收银台 }支付宝返回码10000表示调用成功这个和微信的SUCCESS不一样。SDK 在这里做了一层收敛code字段保持和官方文档一致但data结构做了解析。当面付返回的是二维码内容PC 网站支付返回的是自动提交表单的 HTML两者落到data里的字段完全不同。理解这一点很重要——PaySDK 的统一只是统一了调用入口和返回格式的装载方式没有也不可能让微信和支付宝的返回字段变得一样。业务层拿到结果后分支处理仍然存在只是分支从不同的 API 调用方式降级成了不同返回值的展示逻辑。3.3 返回结果解构为业务层设计一套稳定的响应结构源码里最值得读的就是响应解析这块。微信把结果包在xml里支付宝返回 JSON而 PaySDK 统一把它们解析成数组再套一层固定的外壳。我见过不少项目抛开 SDK 自己请求然后在业务代码里simplexml_load_string()、json_decode()混着用时间一长没人分得清当前接口到底返回什么格式。// 统一响应结构SDK 内部解析后返回 $result [ code SUCCESS, // 业务码各渠道原文业务层判断用 message OK, // 说明信息 data [ // 渠道原文解析后的结构化数据 prepay_id wx3112..., transaction_id 420000..., // 不同渠道该数组字段不同 ], ];这层包装解决的实际问题是业务层不需要关心一个请求是成功还是失败该看哪个字段。微信看return_code和result_code支付宝看code银联可能又有一套。我把这些判断全部下沉到渠道类里业务层只认code、message、data三个键。这样做还有一个好处——记录日志时统一打json_encode($result)排错时不用从一坨原始报文中找字段。4. 异步通知处理签名验证、报文应答和幂等设计这关过不了支付必出事4.1 验签流程先验签再动订单顺序错一天能亏出事故支付集成里最不能出错的就是异步通知。用户在收银台付完钱微信和支付宝会往你配置的notify_url发一个 POST 请求告诉你订单已支付。问题是这个请求任何人都可以伪造而且伪造成本很低——把订单号换成别人的就能让你的系统以为某笔订单付过款了。所以教材写一万遍都要强调收到通知的第一件事是验签验签通过之前一行订单状态代码都不能写。// 异步通知入口 public function notify(Request $request) { $channel $request-input(channel, wechat); // 1. 取原始报文交给 SDK 验签 $notify $pay-channel($channel)-notify(); // 2. 验签失败记录日志直接应答失败让渠道方重试 if (!$notify-isSuccessful()) { Log::warning(支付通知验签失败, [channel $channel, body $request-getContent()]); return $pay-channel($channel)-ackFailed(); } // 3. 验签通过按订单号更新状态 $orderNo $notify-getTradeNo(); // 商户订单号 $tradeNo $notify-getTransactionId();// 渠道流水号 // 幂等检查订单已经是已支付状态则直接应答成功 $order Order::where(out_trade_no, $orderNo)-firstOrFail(); if ($order-status ! Order::STATUS_PENDING) { return $pay-channel($channel)-ack(); } $order-markPaid($tradeNo); return $pay-channel($channel)-ack(); }验签逻辑封装在notify()内部。微信的验签数据源是除去sign字段外的全部参数支付宝是sign和sign_type之外的所有参数拼起来的字符串两边的过滤规则、排序规则、摘要算法都不同但这些全在渠道类里各管各的。业务层只需要调用isSuccessful()。这样设计还有一个附加好处如果渠道方升级了验签算法改动被限制在渠道类内部通知入口文件的代码不需要动。4.2 应答报文微信和支付宝的确认机制完全不同验签通过、订单处理完之后服务器要给渠道方一个应答告诉它我收到了别再重发了。这一步看着简单实际是支付集成里翻车最多的地方——微信要求应答SUCCESS字符串支付宝要求应答success字符串大小写和格式都不同而且两边都要求纯文本不能返回 JSON也不能返回一个空白页面。我用一个表格说明两边的差异方便排查时对照渠道成功应答失败应答应答格式重试策略微信支付SUCCESS非 SUCCESS 字符串如FAIL纯文本间隔递增最多重试 3 次左右支付宝success非 success 字符串如failure纯文本区分大小写间隔递增持续重试较长时间通用错误返回 JSON 错误返回空页面会被判为失败渠道继续重试日志刷屏这里有个容易踩的坑有些框架的控制器会自动把返回内容包装成 JSON或者加一堆调试信息。比如 Laravel 里没调return而是echo了别的调试输出渠道收到的报文头里多了一段X-Powered-By这倒问题不大但如果返回体不是纯的应答字符串渠道会判断应答失败然后反复重发通知。我在这个位置吃过亏本地用 Postman 测试时直接return success没问题部署后发现微信一直在重试查了半天才发现框架全局中间件往响应体追加了调试 HTML。4.3 订单幂等通知重试不是异常是正常流程很多人第一次看到渠道方重发通知会慌以为是程序出 bug。实际上微信和支付宝都会在没收到正确应答、或者网络超时时重发通知间隔从几秒到几分钟不等。如果业务代码不做幂等同一笔订单会被反复标记为已支付、反复增加用户余额。幂等设计的标准做法是订单状态机加唯一约束。订单只有pending待支付、paid已支付、refunded已退款几个状态且paid是不可逆节点。通知处理时先查订单当前状态已经是paid就直接应答成功不再重复执行加余额、发短信这些动作。数据库层面再给out_trade_no加唯一索引双保险挡住并发请求下两条通知同时进来的情况。代码里我习惯把幂等检查放在更新订单之前因为更新操作比检查操作成本高先挡掉重复请求更划算。另一个细节订单状态更新和加余额一定要在同一个数据库事务里。否则出现订单已支付但用户钱包没到账的中间状态又恰好赶上通知重试就会把用户余额加两次。事务把这两个操作绑在一起要么同时成功要么同时失败配合订单状态的幂等检查这个环节才算闭环。5. 支付接口集成排错避坑5 个让 PHP 工程师反复翻车的细节5.1 金额差 100 倍分和元的单位混战现象接口偶尔返回金额无效或订单金额与支付金额不一致。有些订单自己付了 0.01 元却显示扣款 1 元一查订单表存的还是 1。原因微信以分为单位支付宝以元为单位。如果业务层的金额统一用元存储调微信时要乘 100 转成整数分调支付宝时转成字符串元。PaySDK 内部没有做单位换算单位问题属于业务层的职责。很多人看到 SDK 的pay()方法直接接收数组就以为 SDK 会帮他换算结果翻车。解决在业务层做一个金额转换工具函数下单前统一走fen2yuan()/yuan2fen()。另外微信的金额必须是整数PHP 里浮点数1 * 100得到100看着没问题但如果是0.07 * 100浮点误差可能导致结果是7.0000000001转成 int 后变成 7正确换成某些更复杂的金额如9.99 * 100可能得到999.0000001强转 int 后还是 999但如果直接round()处理不当就是另一回事。我的习惯是订单金额一律用整数分存储元只在展示层转换。5.2 证书路径失效部署环境一变报错立刻出现现象本地联调退款接口正常部署到生产服务器后调用退款报curl error 58: unable to set private key file。原因微信 APIv3 的退款、申请转账接口需要加载商户证书。本地环境证书路径写在代码里是./certs/apiclient_key.pem本地当前工作目录恰好是项目根目录生产环境用了不同的目录结构或者入口脚本路径变了相对路径失效。解决初始化配置里强制要求证书路径为绝对路径并且启动时用is_file()或file_exists()检查证书和私钥是否存在。不要用$_SERVER[DOCUMENT_ROOT]拼路径PHP-FPM 和 CLI 环境下该变量的值可能不同。我在项目里是写了一个CryptoHelper::loadCert()方法找不到证书直接抛异常把问题暴露在配置阶段而不是请求阶段。5.3 回调通知重复执行渠道方重试和业务逻辑不幂等等价于事故现象用户支付成功后系统给用户发了多条到账通知短信或者同一笔订单的佣金被重复结算。原因通知入口没有做幂等处理。渠道方在没收到正确应答时会按递增间隔重试每次重试都是一个新的 HTTP 请求如果代码里只判断验签通过就更新订单没有检查订单是否已经是已支付状态重试一次就重复执行一次业务逻辑。解决按第 4 章写的幂等方案处理。核心是两条订单状态字段在更新前做条件判断只有pending状态才能更新为paid数据库给商户订单号加唯一索引双保险。代码层面UPDATE orders SET statuspaid WHERE out_trade_no? AND statuspending这种带条件的更新语句比先查再改更安全。5.4 签名验签失败参数过滤规则和排序规则不一致现象notify()验签偶尔返回false但订单在银行侧已经扣款成功。把原始报文拿给渠道方的签名验证工具验证工具却显示验签通过。原因签名和验签的规则里包含参数过滤逻辑。微信在计算签名时要剔除sign字段、空字符串参数支付宝要剔除sign、sign_type以及值为空的参数。如果 SDK 的过滤规则和商户平台工具里的规则不同步或者代码里在验签前先修改了原始报文比如htmlspecialchars转义就会导致验签失败。解决notify()验签一定要用请求的原始报文不要用经过框架处理和转义后的数据。验签逻辑属于渠道的内部实现业务层不要碰原报文。遇到业务层用自己的规则拼了一次签名时要意识到签名算法是渠道规定的规则不是内网协议不能自创。排查时把原始报文完整记录到日志用官方提供的验签工具逐步对照先看排序再看过滤最后看摘要类型。5.5 沙箱和生产环境混用证书、密钥、AppID 错配现象沙箱环境测试通过切生产后第一笔真实支付就报应用未授权或证书校验失败。检查配置觉得没问题AppID 也对但就是不通。原因微信支付、支付宝都提供沙箱/测试环境。沙箱环境的 AppID、密钥、证书都是测试用的和生产是两套完全独立的凭证。最常见的问题是复制配置时漏改了app_id或者支付宝的沙箱公钥和生产公钥不一样导致生产环境用沙箱公钥验签。解决把环境配置拆成dev.php和prod.php两份文件部署脚本按环境加载。禁止在同一个配置文件里放两套凭证然后靠注释切换——这是安全隐患也是事故隐患。切换生产前用 SDK 提供的query()方法来验证凭证是否有效跑一个真实的订单查询比直接上线试单要稳得多。6. 扩展新渠道的正确姿势用退款接口验证对称设计用沙箱回放做回归PaySDK 真正的价值在扩展性上体现。假设项目要新增一个银联渠道你只需要做三件事写一个实现统一接口的渠道类、配置渠道参数、注册进主入口。渠道类内部要实现的是一组对称方法——pay()下单、query()查单、refund()退款、notify()异步通知处理、ack()应答。这五个方法组成了一个最小可工作的支付渠道少了任何一个业务层调用就会缺胳膊少腿。// 扩展新渠道的最小实现骨架 class UnionpayChannel extends AbstractChannel { public function pay(array $params): array { /* 组装报文、签名、发请求 */ } public function query(array $params): array { /* 查单逻辑 */ } public function refund(array $params): array { /* 退款逻辑 */ } public function notify(): Notify { /* 验签逻辑 */ } public function ack(): Response { /* 应答报文 */ } }新增渠道后验证方法我一般这么做先用沙箱环境跑一遍下单、查单、退款、通知四个全流程然后构造一个伪造的通知报文打到notify入口确认验签逻辑挡得住最后把生产环境某笔历史订单的通知报文保存下来在测试环境重放验证通知处理在真实报文下不翻车。这套回归跑完新渠道才算接稳。我个人的习惯是每次接入新渠道或者修改支付相关代码都会保留一笔真实的支付、退款全流程日志里面存原始请求报文、响应报文、验签结果和订单状态变化。排错时把日志片段拿出来和官方文档对比比猜原因快得多。支付这种涉及真金白银的模块最怕的是感觉应该没问题。这套方法帮我在几个项目里都稳住了希望帮到你。本文还有配套的精品资源点击获取