企业官网建设流程全解析

• 金融科技
• 后端

本文以仓库文档 web/docs/v2/alipay/pay.md 为主体，结合 src/Provider/Alipay.php、src/Traits/AlipayTrait.php、src/Config/AlipayConfig.php 及 src/Shortcut/Alipay 下的各 Shortcut 源码，系统讲解 Yansongda Pay 中支付宝（V2 网关）全部 7 种支付方法的调用方式、订单参数、底层插件链路与返回值处理，帮助开发者一次性掌握支付宝电脑站、手机站、APP、POS、扫码、转账与小程序支付的完整接入方案。

一、支付宝支付方法总览

Yansongda Pay 的支付宝模块（V2 网关）目前支持 7 种支付方法，对应的支付method（即通过$alipay实例调用的方法名）如下表所示：

说明：本仓库 src/Provider/Alipay.php 的文档注释中将手机网站支付对应方法命名为h5，__call魔术方法会把方法名映射为\Yansongda\Pay\Shortcut\Alipay\H5Shortcut（见 src/Shortcut/Alipay/H5Shortcut.php）。旧版 v2 文档中“wap”即手机网站支付的同义叫法，接入时以当前仓库的h5方法为准。

1.1 方法分发机制：Shortcut 自动路由

所有支付方法并非在 Provider 中逐个硬编码，而是通过__call魔术方法自动分发：

// 摘自 src/Provider/Alipay.php public function __call(string $shortcut, array $params): Collection|MessageInterface|Rocket|null { $shortcut = strtolower($shortcut); $plugin = '\Yansongda\Pay\Shortcut\Alipay\\'.Str::studly($shortcut).'Shortcut'; return Artful::shortcut($plugin, ...$params); }

也就是说$alipay->web($order)等价于触发WebShortcut、$alipay->pos($order)触发PosShortcut，依此类推。每个 Shortcut 内部声明一条插件（Plugin）管道，由 Artful 内核按序执行，完成参数装载、签名、请求、验签与响应解析的全过程。

1.2 统一调用入口与配置

支付方法的前置条件是先构建$alipay实例。快速上手可参考 web/docs/v2/alipay/index.md：

use Yansongda\Pay\Pay; $config = [ 'app_id' => '2016082000295641', 'notify_url' => 'http://yansongda.cn/notify.php', 'return_url' => 'http://yansongda.cn/return.php', 'ali_public_key' => '...支付宝公钥...', 'private_key' => '...商户应用私钥...', 'log' => [ // optional 'file' => './logs/alipay.log', 'level' => 'info', // 建议生产环境调整为 info，开发环境为 debug 'type' => 'single', // optional，可选 daily 'max_file' => 30, // optional，当 type 为 daily 时有效，默认 30 天 ], 'http' => [ // optional 'timeout' => 5.0, 'connect_timeout' => 5.0, ], // 'mode' => 'dev', // optional，设置此参数进入沙箱模式 ]; $alipay = Pay::alipay($config);

从 src/Config/AlipayConfig.php 的validateRequired()可以看出，V2/V3 管道强制校验appId、appSecretCert、appPublicCertPath、alipayPublicCertPath四项配置（见 src/Config/AlipayConfig.php），其余如notify_url、return_url、aes_key、service_provider_id、mode等按需配置。网关域名由 src/Provider/Alipay.php 中的URL常量统一管理，沙箱模式下自动切换到https://openapi-sandbox.dl.alipaydev.com。

1.3 关于“客观参数不用配置”

文档反复强调：所有订单配置中，客观参数均不用配置，扩展包已自动处理。这一点在插件源码中有直接体现。例如电脑支付的PayPlugin会自动注入product_code：

// 摘自 src/Plugin/Alipay/V2/Pay/Web/PayPlugin.php $rocket->setDirection(ResponseDirection::class) ->mergePayload([ 'method' => 'alipay.trade.page.pay', 'biz_content' => array_merge( [ 'product_code' => 'FAST_INSTANT_TRADE_PAY', ], $rocket->getParams() ), ]);

刷卡支付的Pos\PayPlugin则会自动注入scene => 'bar_code'（见 src/Plugin/Alipay/V2/Pay/Pos/PayPlugin.php）。你只需关注业务参数，接口级常量由插件补齐。

二、电脑支付（web）

电脑支付对应支付宝alipay.trade.page.pay接口，适合 PC 端网页收银台场景，返回可自动提交的表单 HTML。

2.1 调用示例

$order = [ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'test subject-测试订单', // 'http_method' => 'GET' // 若需以 GET 方式提交表单，请加上此参数；默认使用 POST 方式提交 ]; return $alipay->web($order)->send(); // laravel 框架中请直接 return $alipay->web($order)

要点：

• out_trade_no为商户订单号，示例用time()生成，生产环境建议使用更严谨的唯一订单号；
• total_amount为订单金额（元），支付宝接口要求字符串类型，注意保持两位小数精度；
• subject为订单标题，将展示在支付宝收银台；
• web返回的是Response对象，非 Laravel 环境下需要->send()输出，Laravel 中直接return即可（框架会自动处理 Response）。

2.2 订单配置参数

所有订单配置参数与支付宝官方接口完全一致，兼容全部功能，可参考支付宝开放平台alipay.trade.page.pay接口文档的「请求参数」一栏按需追加，例如seller_id、body、time_expire、goods_detail等。扩展包不会对业务参数做任何裁剪。

2.3 底层插件链路

web方法对应的 WebShortcut 插件管道如下：

StartPlugin → Pay\Web\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → ResponseHtmlPlugin → ParserPlugin

其中PayPlugin装载method=alipay.trade.page.pay与product_code=FAST_INSTANT_TRADE_PAY（见 src/Plugin/Alipay/V2/Pay/Web/PayPlugin.php），AddPayloadSignaturePlugin完成 RSA2 签名，ResponseHtmlPlugin将结果组装为自动提交表单的 HTML。相关插件实现可查阅 src/Plugin/Alipay/V2 目录，测试用例位于 tests/Plugin/Alipay/V2/Pay。

三、手机网站支付（h5 / wap）

手机网站支付对应支付宝alipay.trade.wap.pay接口，适用于手机浏览器内拉起支付宝收银台。

3.1 调用示例

$order = [ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'test subject-测试订单', // 'http_method' => 'GET' // 若想以 GET 方式提交，请加上此参数；默认使用 POST 方式提交 ]; return $alipay->h5($order)->send(); // laravel 框架中请直接 return $alipay->h5($order)

与web的差异点：

• http_method参数对 wap/h5 场景尤其常用——默认 POST 提交，如需 GET 请显式指定；
• 其余订单参数同样与官方alipay.trade.wap.pay接口「请求参数」保持一致，product_code等客观参数无需配置。

3.2 底层插件链路

H5Shortcut 与 Web 完全同构：

StartPlugin → Pay\H5\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → ResponseHtmlPlugin → ParserPlugin

区别仅在业务插件 src/Plugin/Alipay/V2/Pay/H5/PayPlugin.php 中装载的method不同（alipay.trade.wap.pay）。

四、APP 支付（app）

APP 支付对应支付宝alipay.trade.app.pay接口，用于原生 APP 拉起支付宝客户端完成支付。

4.1 调用示例

$order = [ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'test subject-测试订单', ]; // 将返回字符串，供后续 APP 调用；调用方式不在本文档讨论范围内，请参考官方文档 return $alipay->app($order)->send(); // laravel 框架中请直接 return $alipay->app($order)

注意app的返回体与web/h5不同：它返回的不是整页 HTML，而是一段可供 APP 端直接使用的订单参数字符串（支付宝 SDK 调用PayResultActivity或AliPay客户端所需的 orderString）。APP 端如何携带并拉起支付宝不在本文档范围内。

4.2 订单配置参数

所有订单配置参数与官方alipay.trade.app.pay接口无差别，客观参数（如product_code）已由扩展包自动处理，其余业务参数按官方文档「请求参数」一栏追加即可。

4.3 底层插件链路

AppShortcut 的管道与 web/h5 有一个显著差异：

StartPlugin → Pay\App\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → ResponseInvokeStringPlugin → ParserPlugin

• 没有AddRadarPlugin：因为 APP 支付不直接发起 HTTP 请求，而是生成待签名字符串交给 APP 端；
• 末尾使用 ResponseInvokeStringPlugin 而非ResponseHtmlPlugin，输出的是订单字符串而不是表单 HTML。

五、刷卡支付（pos）

刷卡支付（付款码 / 被扫）对应支付宝alipay.trade.pay接口，适用于线下收银台扫码枪扫描用户付款码的场景，同步返回支付结果。

5.1 调用示例

$order = [ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'test subject-刷卡支付', 'auth_code' => '289756915257123456', // 用户付款码（条码） ]; $result = $alipay->pos($order);

要点：

• auth_code为扫码枪读取到的用户付款码，必填；
• pos返回Collection，可直接读取支付宝同步返回的交易结果，例如$result->trade_no（支付宝交易号）、$result->total_amount等；
• 底层 Pos\PayPlugin 会自动注入scene => 'bar_code'。

5.2 订单配置参数

所有订单配置参数与官方alipay.trade.pay接口完全一致，客观参数（scene等）已自动处理，其余参数参考官方「请求参数」一栏。

5.3 底层插件链路

PosShortcut 管道如下，注意与 web/h5 相比多了验签环节：

StartPlugin → Pay\Pos\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → VerifySignaturePlugin → ResponsePlugin → ParserPlugin

由于pos同步拿到服务器响应数据，管道中通过VerifySignaturePlugin对响应做 RSA2 验签（实现见 src/Traits/AlipayTrait.php 的verifyAlipaySign），再用ResponsePlugin将Rocket转为Collection。

六、扫码支付（scan）

扫码支付（正扫）对应支付宝alipay.trade.precreate接口，商户生成二维码、用户扫码付款，属于异步支付——下单接口只返回二维码内容，支付结果通过异步通知或主动查询获得。

6.1 调用示例

$order = [ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'test subject-刷卡支付', ]; $result = $alipay->scan($order); // 二维码内容： $qr = $result->qr_code;

要点：

• 返回Collection，其中qr_code字段即为二维码内容，可直接交给前端生成二维码图片；
• 下单成功后建议结合 web/docs/v2/alipay/find.md 中的查询方法轮询订单状态，或依赖 web/docs/v2/alipay/callback.md 的异步通知确认支付结果。

6.2 订单配置参数

所有订单配置参数与官方alipay.trade.precreate接口一致，客观参数已自动处理。业务参数如timeout_express（扫码支付建议显式设置二维码超时时间）、goods_detail等按官方「请求参数」一栏追加即可。底层 Scan\PayPlugin 负责装载method=alipay.trade.precreate。

七、账户转账（transfer）

账户转账对应支付宝alipay.fund.trans.uni.transfer接口，用于单笔转账到支付宝账户。

7.1 调用示例

$order = [ 'out_biz_no' => time(), 'trans_amount' => '0.01', 'product_code' => 'TRANS_ACCOUNT_NO_PWD', 'payee_info' => [ 'identity' => 'ghdhjw7124@sandbox.com', 'identity_type' => 'ALIPAY_LOGON_ID', ], ]; $result = $alipay->transfer($order);

要点：

• out_biz_no为商户转账订单号；
• product_code转账场景建议显式指定TRANS_ACCOUNT_NO_PWD；
• payee_info.identity为收款方标识，identity_type为标识类型（如ALIPAY_LOGON_ID表示登录号/邮箱）；
• 返回Collection，可读取$result->order_id、$result->pay_fund_order_id等字段。

7.2 查询转账订单

转账属于资金类操作，务必跟进结果。可通过find方法并传入第二个参数transfer指定查询转账订单：

$order = [ 'out_trade_no' => '1514027114', ]; // $order = '1514027114'; // 也可以直接传字符串 $result = $alipay->find($order, 'transfer');

7.3 订单配置参数

所有订单配置参数与官方alipay.fund.trans.uni.transfer接口完全一致，客观参数无需配置，其余按官方「请求参数」一栏使用。

7.4 底层插件链路

TransferShortcut 与 pos 同构，业务插件为 src/Plugin/Alipay/V2/Fund/Transfer 下的TransferPlugin：

StartPlugin → TransferPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → VerifySignaturePlugin → ResponsePlugin → ParserPlugin

八、小程序支付（mini）

小程序支付对应支付宝alipay.trade.create接口，用于支付宝小程序内拉起支付收银台。

8.1 调用示例

$order = [ 'out_trade_no' => time(), 'subject' => 'test subject-小程序支付', 'total_amount' => '0.01', 'buyer_id' => 2088622190161234, // 用户支付宝 UID ]; $result = $alipay->mini($order);

要点：

• buyer_id为小程序内获取到的用户支付宝 UID（2088 开头的数字），必填；
• 返回Collection，可读取trade_no等字段，后续由小程序端调用my.tradePay拉起收银台；
• 小程序支付的整体接入流程请参考支付宝小程序官方支付接入文档。

8.2 订单配置参数

所有订单配置参数与官方alipay.trade.create接口一致，客观参数（如product_code）已自动处理，其余业务参数按官方「请求参数」一栏追加。对应 Shortcut 与插件位于 src/Shortcut/Alipay/MiniShortcut.php 与 src/Plugin/Alipay/V2/Pay/Mini。

九、返回值类型与处理方式

各支付方法的返回值已在首节表格中标注，返回值只会是两种类型之一：

1. Symfony\Component\HttpFoundation\Response—— 用于web、h5、app三个方法；
2. Yansongda\Supports\Collection—— 用于pos、scan、transfer、mini四个方法。

9.1 Response 类型

// 非框架环境 return $response->send(); // Laravel 等框架环境 return $response;

Response承载的是需要输出给浏览器的表单 HTML（web/h5）或 APP 端订单字符串（app），直接send()输出即可，框架中直接返回交给框架处理。

9.2 Collection 类型

// 通过属性方式访问服务器返回数据 $result->qr_code; // scan：二维码内容 $result->trade_no; // pos/transfer/mini：支付宝交易号 $result->order_id; // transfer：转账单号

Collection底层来自Yansongda\Supports组件，支持->xxx属性访问与数组式访问，数据即支付宝接口同步返回的原始字段。建议在业务代码中先判断$result->code（10000表示成功）再做后续流程。

十、配套操作与注意事项

支付之外，同一套$alipay实例还提供完整的交易闭环能力，可配合以下文档使用：

• 查询订单：$alipay->find($order)，并支持find($order, 'transfer')查询转账订单；
• 退款：$alipay->refund($order)；
• 取消订单 与 关闭订单；
• 异步回调处理：$alipay->verify()验签 +$alipay->success()确认；
• 响应签名机制 与 下载账单。

注意事项：

1. 沙箱调试：在 web/docs/v2/alipay/index.md 的配置基础上增加'mode' => 'dev'即可进入沙箱模式，此时网关自动切换为沙箱地址；
2. 服务商模式：配置'mode' => 'service'并补充'pid'参数即可，插件管道会自动注入sys_service_provider_id（实现见 src/Traits/AlipayTrait.php 的loadAlipayServiceProvider）；
3. 加密方式：当前仅支持支付宝官方推荐的RSA2（SHA256withRSA），相关验签逻辑见 src/Traits/AlipayTrait.php 的verifyAlipaySign，响应签名校验失败会抛出InvalidSignException；
4. 金额精度：total_amount、trans_amount等金额字段请使用字符串类型，避免浮点误差。

通过以上 7 种支付方法及其插件管道，开发者可以在 Yansongda Pay 中用一个统一的$alipay实例覆盖电脑、手机、APP、线下扫码与被扫、转账及小程序全场景的支付宝收款需求。

• 金融科技
• 后端