yansongda/pay 支付宝支付实战指南：网页、H5、APP、小程序、刷卡、扫码与转账七种快捷支付方式

• 金融科技
• 后端

本指南以支付宝开放平台的七种核心收单场景为脉络，系统讲解 yansongda/pay 中Pay::alipay()->web()、h5()、app()、mini()、pos()、scan()、transfer()七个快捷方法的调用方式、订单参数约定与底层插件执行链路。读完本文，你将能够在自己的 PHP 项目中以统一、简洁的 API 接入支付宝全部主流支付方式，并理解扩展包“客观参数自动补全、业务参数与官方一致”的设计原则。

快捷方式总览

支付宝支付在 yansongda/pay 中直接内置支持以下快捷方式，每个快捷方式对应一个支付宝开放平台接口，调用方只需传入业务订单参数即可：

其中web、h5、app三个快捷方式返回Response（可渲染的表单或唤起串），其余返回Collection（结构化响应集合，可通过属性或get()方法读取字段）。这一定位与各快捷方式底层的插件链严格对应（详见文末“插件化内核”一节）。

通用约定：客观参数自动处理

使用任何支付快捷方式前，均需先加载配置：

Pay::config($this->config);

所有订单配置中，客观参数均不用配置，扩展包已经为大家自动处理了，比如网页支付中的product_code（默认注入FAST_INSTANT_TRADE_PAY）、小程序支付中的product_code（默认注入JSAPI_PAY）、转账中的biz_scene（默认DIRECT_TRANSFER）与product_code（默认TRANS_ACCOUNT_NO_PWD）等。

其余所有订单配置参数与支付宝官方接口无任何差别，兼容所有功能，完整参数列表请以支付宝开放平台对应接口文档的「请求参数」一栏为准。这意味着你无需记忆扩展包特有的参数名，直接从官方文档复制参数结构即可无缝使用。

网页支付（web）

网页支付对应支付宝 PC 收银台（alipay.trade.page.pay），适合桌面浏览器场景，返回值为可渲染的 HTML 表单Response。

基本用法

Pay::config($this->config); return Pay::alipay()->web([ 'out_trade_no' => ''.time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 1', ]);

GET 方式提交

扩展包默认以 POST 方式提交表单，若您想使用 GET 方式提交请求，只需在参数中增加['_method' => 'get']：

Pay::config($this->config); return Pay::alipay()->web([ 'out_trade_no' => ''.time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 1', '_method' => 'get', ]);

_method为扩展包私有控制参数，不会进入biz_content业务字段，仅影响提交方式。

底层实现

从源码看，WebShortcut 的插件链为StartPlugin → Pay\Web\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → ResponseHtmlPlugin → ParserPlugin。其中 Pay\Web\PayPlugin 会向biz_content自动合并默认值：

$rocket->mergePayload([ 'method' => 'alipay.trade.page.pay', 'biz_content' => array_merge( ['product_code' => 'FAST_INSTANT_TRADE_PAY'], $rocket->getParams() ), ]);

即product_code由扩展包注入，你传入的out_trade_no、total_amount、subject等业务参数原样并入。ResponseHtmlPlugin负责将签名后的请求组装为自动提交的 HTML 表单响应。

订单配置参数

• 无需配置：product_code等客观参数（扩展包自动处理）。
• 业务参数与官方alipay.trade.page.pay完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。

H5 支付（h5）

H5 支付对应支付宝手机网站支付（alipay.trade.wap.pay），适合手机浏览器场景，返回值为可跳转的 HTMLResponse。

基本用法

Pay::config($this->config); return Pay::alipay()->h5([ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 01', 'quit_url' => 'https://yansongda.cn', ]);

quit_url为用户支付中断后跳转的退出地址，属 H5 场景常用业务参数，按官方规则传即可。

GET 方式提交

与网页支付一致，可通过'_method' => 'get'切换为 GET 提交：

Pay::config($this->config); return Pay::alipay()->h5([ 'out_trade_no' => ''.time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 1', '_method' => 'get', ]);

底层实现

H5Shortcut 的插件链与 web 完全同构：StartPlugin → Pay\H5\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → ResponseHtmlPlugin → ParserPlugin。Pay\H5\PayPlugin 仅注入method => alipay.trade.wap.pay并原样透传biz_content，不额外注入product_code——这与官方 wap 支付接口的参数要求一致。

订单配置参数

• 无需配置客观参数，扩展包已自动处理。
• 业务参数与官方alipay.trade.wap.pay完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。

APP 支付（app）

APP 支付对应alipay.trade.app.pay，用于支付宝 App 内唤起支付，返回值为可直接交给移动端调起支付宝的字符串（Response）。

基本用法

Pay::config($this->config); // 后续 APP 调用方式不在本文档讨论范围内，请参考官方文档。 return Pay::alipay()->app([ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 01', ]);

返回值是签名后的“唤起串”（orderStr），移动端拿到后按支付宝 SDK 规范调起支付；具体 APP 侧集成步骤请参考支付宝官方 APP 支付文档。

底层实现

AppShortcut 的插件链为：StartPlugin → Pay\App\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → ResponseInvokeStringPlugin → ParserPlugin。与 web/h5 不同，APP 支付没有AddRadarPlugin与ResponseHtmlPlugin，而是使用ResponseInvokeStringPlugin产出唤起字符串。Pay\App\PayPlugin 注入method => alipay.trade.app.pay并原样透传biz_content。

订单配置参数

• 无需配置客观参数，扩展包已自动处理。
• 业务参数与官方alipay.trade.app.pay完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。

小程序支付（mini）

小程序支付对应alipay.trade.create（JSAPI 场景），返回值类型为Collection，可读取支付宝返回的交易号等字段。

基本用法

Pay::config($this->config); $result = Pay::alipay()->mini([ 'out_trade_no' => time().'', 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 01', 'buyer_id' => '2088622190161234', ]); return $result->get('trade_no'); // 支付宝交易号 // return $result->trade_no;

Collection既支持get('trade_no')方式读取，也支持属性式访问$result->trade_no。buyer_id为买家支付宝用户 ID，用于小程序场景下锁定付款人。

底层实现

MiniShortcut 的插件链为：StartPlugin → Pay\Mini\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → VerifySignaturePlugin → ResponsePlugin → ParserPlugin。相比 web/h5/app，mini 增加了VerifySignaturePlugin（验签）与ResponsePlugin（结构化解析），因此返回Collection。Pay\Mini\PayPlugin 会注入：

$rocket->mergePayload([ 'method' => 'alipay.trade.create', 'biz_content' => array_merge( ['product_code' => 'JSAPI_PAY'], $rocket->getParams(), ), ]);

即product_code => JSAPI_PAY由扩展包自动补全。

订单配置参数

• 无需配置客观参数，扩展包已自动处理（含product_code）。
• 业务参数与官方alipay.trade.create完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。
• 小程序支付接入流程请参考支付宝开放平台「小程序支付」接入文档。

刷卡支付（pos，付款码/被扫码）

刷卡支付对应付款码（被扫）场景（alipay.trade.pay），用户在收银台出示付款码，商家扫码完成扣款，返回值类型为Collection。

基本用法

Pay::config($this->config); $result = Pay::alipay()->pos([ 'out_trade_no' => time(), 'auth_code' => '284776044441477959', 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 01', ]);

auth_code为用户的付款码（条码/二维码内容），是刷卡支付的必传业务参数。

底层实现

PosShortcut 的插件链为：StartPlugin → Pay\Pos\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → VerifySignaturePlugin → ResponsePlugin → ParserPlugin，同样经过验签与结构化解析，返回Collection。

订单配置参数

• 无需配置客观参数，扩展包已自动处理。
• 业务参数与官方alipay.trade.pay完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。

扫码支付（scan）

扫码支付对应预下单接口alipay.trade.precreate：服务端生成订单二维码，用户用支付宝 App 扫码完成付款，返回值类型为Collection，可通过qr_code字段获取二维码内容。

基本用法

Pay::config($this->config); $result = Pay::alipay()->scan([ 'out_trade_no' => time(), 'total_amount' => '0.01', 'subject' => 'yansongda 测试 - 01', ]); return $result->qr_code; // 二维码 url

底层实现

ScanShortcut 的插件链为：StartPlugin → Pay\Scan\PayPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → VerifySignaturePlugin → ResponsePlugin → ParserPlugin。Pay\Scan\PayPlugin 注入method => alipay.trade.precreate并原样透传biz_content；响应中的qr_code即为可生成二维码图片的 URL 内容。

订单配置参数

• 无需配置客观参数，扩展包已自动处理。
• 业务参数与官方alipay.trade.precreate完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。

账户转账（transfer）

账户转账对应单笔转账接口alipay.fund.trans.uni.transfer，用于向支付宝账户（含沙箱账户）打款，返回值类型为Collection。

基本用法

Pay::config($this->config); $result = Pay::alipay()->transfer([ 'out_biz_no' => '202106051432', 'trans_amount' => '0.01', 'product_code' => 'TRANS_ACCOUNT_NO_PWD', 'biz_scene' => 'DIRECT_TRANSFER', 'payee_info' => [ 'identity' => 'ghdhjw7124@sandbox.com', 'identity_type' => 'ALIPAY_LOGON_ID', 'name' => '沙箱环境' ], ]);

其中out_biz_no为商户转账订单号，trans_amount为转账金额，payee_info为收款方信息（identity收款账户、identity_type账户类型、name真实姓名）。

底层实现

TransferShortcut 的插件链为：StartPlugin → Fund\Transfer\Fund\TransferPlugin → FormatPayloadBizContentPlugin → AddPayloadSignaturePlugin → AddRadarPlugin → VerifySignaturePlugin → ResponsePlugin → ParserPlugin。TransferPlugin 会自动注入默认业务参数：

$rocket->mergePayload([ 'method' => 'alipay.fund.trans.uni.transfer', 'biz_content' => array_merge( [ 'biz_scene' => 'DIRECT_TRANSFER', 'product_code' => 'TRANS_ACCOUNT_NO_PWD', ], $rocket->getParams(), ), ]);

因此即使你不显式传入product_code与biz_scene，扩展包也会按单笔无密转账（TRANS_ACCOUNT_NO_PWD/DIRECT_TRANSFER）补全；显式传入时以你的参数为准（array_merge后置覆盖）。

订单配置参数

• 所有订单配置中，客观参数均不用配置，扩展包已经为大家自动处理了。
• 业务参数与官方alipay.fund.trans.uni.transfer完全一致，兼容所有功能，请参考支付宝开放平台该接口文档的「请求参数」一栏。

:::tip 转账查询等后续操作，请参考 查询文档；支付结果的通知处理可参考 回调文档。 :::

插件化内核：七个快捷方式背后的统一流水线

从上面的源码分析可以看出，七个快捷方式的差异仅体现在插件组合上，整体遵循同一套 Artful 流水线范式，可归纳为三类：

• 表单/唤起类（web、h5、app）：以ResponseHtmlPlugin/ResponseInvokeStringPlugin收尾，不验签、不解析，直接返回可消费的Response；
• 接口调用类（mini、pos、scan、transfer）：以VerifySignaturePlugin + ResponsePlugin收尾，对响应验签并解析为Collection；
• 公共环节：StartPlugin负责初始化环境与配置，FormatPayloadBizContentPlugin统一组装biz_content，AddPayloadSignaturePlugin完成请求签名，AddRadarPlugin负责请求链路追踪（Radar）。

快捷方式本身是实现Yansongda\Artful\Contract\ShortcutInterface的类，仅声明插件类列表，由 AlipayTrait 与 Alipay 服务提供者 统一调度执行。这带来两个直接收益：调用方只需写业务参数，无需关心签名、验签与请求细节；且任何快捷方式都可拆解、可组合、可自定义。需要更底层的自定义能力时，可以参考 内核文档 与 快速开始。

延伸阅读

• 支付宝支付查询：订单查询、转账查询等
• 支付宝支付退款：退款与退款查询
• 支付宝支付回调：异步通知的接收与验签
• 支付宝快速开始：配置项（应用 ID、公私钥、证书模式等）完整说明

• 金融科技
• 后端