111
--- title: 斗拱考试实战：支付宝正扫+退款场景完整实现与踩坑记录 date: 2026-01-07 author: 夏末浅笑 tags: categories: --- # 斗拱考试实战：支付宝正扫+退款场景完整实现与踩坑记录 **作者**：夏末浅笑 **博客**：(https://blog.ccswust.org/) **创建日期**：2026-01-07 ## 前言 最近需要完成斗拱考试的支付宝正扫+退款场景，整个过程中遇到了不少坑，特此记录下来，希望能帮助到后来者。本文将详细介绍如何使用汇付支付的PHP SDK实现PC端支付宝扫码支付和交易退款功能，并深入分析常见问题的解决方案。 ## 一、项目背景 ### 考试要求 - **聚合正扫**：调用聚合正扫API，`trade_type = A_NATIVE` - **支付金额**：向个人账户内支付≤¥1.00金额 - **交易退款**：调用交易退款API，将支付款退还给用户 - **流水号格式**：`req_seq_id`必须包含用户ID和请求日期，格式为：`用户ID_日期_随机数` ### 技术栈 - **后端**：PHP 7.4 + 汇付支付SDK V2.0.23 - **前端**：原生JavaScript + 官方PC端SDK - **部署环境**：Nginx + HTTPS ## 二、项目结构 huifu_exam_complete/ ├── api/ # 后端API接口 │ ├── pc_pay.php # PC端支付宝扫码支付接口 │ ├── pc_refund.php # 交易退款接口 │ ├── query.php # 交易查询接口 │ ├── notify.php # 异步通知处理 │ └── loader.php # SDK加载器 ├── public/ # 前端页面 │ └── pc/ # PC端收银台 │ ├── cashier.html # 收银台页面 │ ├── refund.html # 退款测试页面 │ ├── pay.js # 支付逻辑 │ └── config/ # 配置文件 └── sdk/ # 汇付支付SDK └── BsPaySdk/ # PHP SDK核心文件 ## 三、核心实现 ### 3.1 支付接口实现 支付接口使用聚合正扫API，交易类型为A_NATIVE（支付宝扫码）。 ```php post("v3.trade.payment.jspay", $paramsInfo, '', 'default'); // 4. 处理响应 if (!$result || $result->isError()) { // 失败处理 } else { // 成功处理，返回二维码 } ?> 关键点： 流水号格式必须包含用户ID和日期 交易类型必须为A_NATIVE 支付金额必须≥0.10元（手续费限制） 3.2 退款接口实现 退款接口使用V2版本的交易退款API。 post("v2.trade.payment.scanpay.refund", $paramsInfo, '', 'default'); // 5. 处理响应 if (!$result || $result->isError()) { // 失败处理 } else { // 成功处理 } } catch (Exception $e) { // 异常处理 } ?> 关键点： 必须使用V2版本退款接口（v2.trade.payment.scanpay.refund） 必须使用汇付全局流水号（hf_seq_id）作为原交易标识 namespace声明必须在文件第一行 四、踩坑记录 坑1：SDK类加载失败 错误信息：Fatal error: Class 'BsPaySdk\request\BaseRequest' not found 原因：直接加载请求类文件，但没有加载SDK的init.php文件，导致父类BaseRequest没有被正确加载。 解决方案：使用loader.php统一加载SDK，确保类加载顺序正确。 // loader.php require_once dirname...
