@alipay/alipay-aipay 1.7.0 → 1.7.2

package/skill-pre/references/integration/modules/code-examples/php/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/345/205/263/351/227/255/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,59 @@
+# 统一收单交易关闭接口 - PHP 示例
+
+## 请求示例
+
+```php
+<?php
+require_once __DIR__ . '/aop/AopClient.php';
+require_once __DIR__ . '/aop/request/AlipayTradeCloseRequest.php';
+
+// 初始化 SDK（PHP 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+$aop = new AopClient();
+$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
+// 沙箱环境: $aop->gatewayUrl = 'https://openapi-sandbox.dl.alipaydev.com/gateway.do';
+$aop->appId = '<-- 请填写您的AppId，例如：20190xxxxxx -->';
+$aop->rsaPrivateKey = '<-- 请填写您的应用私钥（PKCS#1格式），例如：MIIE...（脱敏示例） -->';
+$aop->alipayrsaPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->';
+$aop->format = 'json';
+$aop->postCharset = 'UTF-8';
+$aop->signType = 'RSA2';
+
+// 构造请求参数
+$request = new AlipayTradeCloseRequest();
+$bizContent = [
+    'out_trade_no' => 'MERCHANT_ORDER_NO_PLACEHOLDER',  // 商户订单号，与 trade_no 二选一
+    // 'trade_no' => 'ALIPAY_TRADE_NO_PLACEHOLDER',  // 支付宝交易号，同时传时以 trade_no 为准
+];
+$request->setBizContent(json_encode($bizContent, JSON_UNESCAPED_UNICODE));
+
+// 调用接口
+$response = $aop->execute($request);
+$responseApiName = str_replace('.', '_', $request->getApiMethodName()) . '_response';
+$result = $response->$responseApiName;
+
+if (!empty($result->code) && $result->code == '10000') {
+    echo "交易关闭成功";
+} else {
+    echo "调用失败: " . $result->sub_code . " - " . $result->sub_msg;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill-pre/references/integration/modules/code-examples/php/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/346/237/245/350/257/242/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,73 @@
+# 统一收单交易查询接口 - PHP 示例
+
+## 请求示例
+
+```php
+<?php
+require_once __DIR__ . '/aop/AopClient.php';
+require_once __DIR__ . '/aop/request/AlipayTradeQueryRequest.php';
+
+// 初始化 SDK（PHP 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+$aop = new AopClient();
+$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
+// 沙箱环境: $aop->gatewayUrl = 'https://openapi-sandbox.dl.alipaydev.com/gateway.do';
+$aop->appId = '<-- 请填写您的AppId，例如：20190xxxxxx -->';
+$aop->rsaPrivateKey = '<-- 请填写您的应用私钥（PKCS#1格式），例如：MIIE...（脱敏示例） -->';
+$aop->alipayrsaPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->';
+$aop->format = 'json';
+$aop->postCharset = 'UTF-8';
+$aop->signType = 'RSA2';
+
+// 构造请求参数
+$request = new AlipayTradeQueryRequest();
+$bizContent = [
+    'out_trade_no' => 'MERCHANT_ORDER_NO_PLACEHOLDER',  // 商户订单号，与 trade_no 二选一
+    // 'trade_no' => 'ALIPAY_TRADE_NO_PLACEHOLDER',  // 支付宝交易号，同时传时以 trade_no 为准
+];
+$request->setBizContent(json_encode($bizContent, JSON_UNESCAPED_UNICODE));
+
+// 调用接口
+$response = $aop->execute($request);
+$responseApiName = str_replace('.', '_', $request->getApiMethodName()) . '_response';
+$result = $response->$responseApiName;
+
+if (!empty($result->code) && $result->code == '10000') {
+    $businessStates = [
+        'TRADE_SUCCESS' => 'PAID',
+        'TRADE_FINISHED' => 'PAID',
+        'WAIT_BUYER_PAY' => 'PENDING_PAYMENT',
+        'TRADE_CLOSED' => 'CLOSED',
+    ];
+    $businessState = $businessStates[$result->trade_status] ?? 'UNKNOWN';
+    echo "业务状态: {$businessState}, 支付宝状态: {$result->trade_status}, 订单金额: {$result->total_amount}";
+} else {
+    echo "调用失败: " . $result->sub_code . " - " . $result->sub_msg;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER",
+    "trade_status": "TRADE_SUCCESS",
+    "total_amount": "88.88",
+    "buyer_pay_amount": "8.88",
+    "receipt_amount": "15.25",
+    "buyer_logon_id": "159****5620",
+    "buyer_user_id": "<BUYER_USER_ID>",
+    "send_pay_date": "2014-11-27 15:45:57"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill-pre/references/integration/modules/code-examples/php/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/351/200/200/346/254/276/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,69 @@
+# 统一收单交易退款接口 - PHP 示例
+
+## 请求示例
+
+```php
+<?php
+require_once __DIR__ . '/aop/AopClient.php';
+require_once __DIR__ . '/aop/request/AlipayTradeRefundRequest.php';
+
+// 初始化 SDK（PHP 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+$aop = new AopClient();
+$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
+// 沙箱环境: $aop->gatewayUrl = 'https://openapi-sandbox.dl.alipaydev.com/gateway.do';
+$aop->appId = '<-- 请填写您的AppId，例如：20190xxxxxx -->';
+$aop->rsaPrivateKey = '<-- 请填写您的应用私钥（PKCS#1格式），例如：MIIE...（脱敏示例） -->';
+$aop->alipayrsaPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->';
+$aop->format = 'json';
+$aop->postCharset = 'UTF-8';
+$aop->signType = 'RSA2';
+
+// 构造请求参数
+$request = new AlipayTradeRefundRequest();
+$bizContent = [
+    'out_trade_no' => 'MERCHANT_ORDER_NO_PLACEHOLDER',         // 商户订单号
+    // 'trade_no' => 'ALIPAY_TRADE_NO_PLACEHOLDER', // 支付宝交易号，与 out_trade_no 二选一
+    'refund_amount' => '0.01',                     // 使用十进制定点金额；调用前校验累计退款不超过原订单实付金额
+    'refund_reason' => '测试退款',                  // 退款原因
+    'out_request_no' => 'OUT_REQUEST_NO_PLACEHOLDER', // 新退款使用新编号；同一退款失败重试必须复用原编号和原参数
+];
+$request->setBizContent(json_encode($bizContent, JSON_UNESCAPED_UNICODE));
+
+// 调用接口
+$response = $aop->execute($request);
+$responseApiName = str_replace('.', '_', $request->getApiMethodName()) . '_response';
+$result = $response->$responseApiName;
+
+if (!empty($result->code) && $result->code == '10000') {
+    if (($result->fund_change ?? null) === 'Y') {
+        echo "退款资金已发生变化，退款金额: " . $result->refund_fee;
+    } else {
+        echo "退款结果待确认：使用同一 out_request_no 调用 alipay.trade.fastpay.refund.query";
+    }
+} else {
+    echo "调用失败: " . $result->sub_code . " - " . $result->sub_msg;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER",
+    "buyer_logon_id": "159****5620",
+    "fund_change": "Y",
+    "refund_fee": "0.01"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill-pre/references/integration/modules/code-examples/php/1-/351/200/232/347/224/250/346/216/245/345/217/243//347/273/237/344/270/200/346/224/266/345/215/225/344/272/244/346/230/223/351/200/200/346/254/276/346/237/245/350/257/242/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,65 @@
+# 统一收单交易退款查询接口 - PHP 示例
+
+## 请求示例
+
+```php
+<?php
+require_once __DIR__ . '/aop/AopClient.php';
+require_once __DIR__ . '/aop/request/AlipayTradeFastpayRefundQueryRequest.php';
+
+// 初始化 SDK（PHP 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+$aop = new AopClient();
+$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
+// 沙箱环境: $aop->gatewayUrl = 'https://openapi-sandbox.dl.alipaydev.com/gateway.do';
+$aop->appId = '<-- 请填写您的AppId，例如：20190xxxxxx -->';
+$aop->rsaPrivateKey = '<-- 请填写您的应用私钥（PKCS#1格式），例如：MIIE...（脱敏示例） -->';
+$aop->alipayrsaPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->';
+$aop->format = 'json';
+$aop->postCharset = 'UTF-8';
+$aop->signType = 'RSA2';
+
+// 构造请求参数
+$request = new AlipayTradeFastpayRefundQueryRequest();
+$bizContent = [
+    'out_trade_no' => 'MERCHANT_ORDER_NO_PLACEHOLDER',     // 商户订单号
+    'out_request_no' => 'OUT_REQUEST_NO_PLACEHOLDER',          // 退款请求号，必填
+];
+$request->setBizContent(json_encode($bizContent, JSON_UNESCAPED_UNICODE));
+
+// 调用接口
+$response = $aop->execute($request);
+$responseApiName = str_replace('.', '_', $request->getApiMethodName()) . '_response';
+$result = $response->$responseApiName;
+
+if (!empty($result->code) && $result->code == '10000') {
+    // refund_status: REFUND_SUCCESS 表示退款成功
+    echo "退款状态: " . $result->refund_status . ", 退款金额: " . $result->refund_amount;
+} else {
+    echo "调用失败: " . $result->sub_code . " - " . $result->sub_msg;
+}
+```
+
+## 响应示例
+### 正常示例
+```json
+{
+    "code": "10000",
+    "msg": "Success",
+    "trade_no": "ALIPAY_TRADE_NO_PLACEHOLDER",
+    "out_trade_no": "MERCHANT_ORDER_NO_PLACEHOLDER",
+    "out_request_no": "OUT_REQUEST_NO_PLACEHOLDER",
+    "total_amount": "0.01",
+    "refund_amount": "0.01",
+    "refund_status": "REFUND_SUCCESS",
+    "gmt_refund_pay": "2014-11-27 15:45:57"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill-pre/references/integration/modules/code-examples/php/2-/347/275/221/347/253/231/346/224/257/344/273/230//347/273/237/344/270/200/346/224/266/345/215/225/344/270/213/345/215/225/345/271/266/346/224/257/344/273/230/351/241/265/351/235/242/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,59 @@
+# 统一收单下单并支付页面接口 - PHP 示例
+
+## 请求示例
+
+```php
+<?php
+require_once __DIR__ . '/aop/AopClient.php';
+require_once __DIR__ . '/aop/request/AlipayTradePagePayRequest.php';
+
+// 初始化 SDK（PHP 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用）
+$aop = new AopClient();
+$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
+// 沙箱环境: $aop->gatewayUrl = 'https://openapi-sandbox.dl.alipaydev.com/gateway.do';
+$aop->appId = '<-- 请填写您的AppId，例如：20190xxxxxx -->';
+$aop->rsaPrivateKey = '<-- 请填写您的应用私钥（PKCS#1格式），例如：MIIE...（脱敏示例） -->';
+$aop->alipayrsaPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->';
+$aop->format = 'json';
+$aop->postCharset = 'UTF-8';
+$aop->signType = 'RSA2';
+
+// 构造请求参数
+$request = new AlipayTradePagePayRequest();
+$notifyUrl = trim(getenv('ALIPAY_NOTIFY_URL') ?: '');
+if ($notifyUrl !== '') {
+    $request->setNotifyUrl($notifyUrl);  // 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 null、空字符串或占位 URL
+}
+$request->setReturnUrl('https://your-domain.com/return');  // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
+
+$bizContent = [
+    'out_trade_no' => date('YmdHis') . mt_rand(1000, 9999),  // 商户订单号
+    'total_amount' => '0.01',                                // 订单总金额
+    'subject' => '测试商品',                                   // 订单标题
+    'product_code' => 'FAST_INSTANT_TRADE_PAY',              // 网站支付固定值
+];
+$request->setBizContent(json_encode($bizContent, JSON_UNESCAPED_UNICODE));
+
+// ⚠️ 网站支付必须使用 pageExecute()，不能使用 execute()
+// ⚠️ 必须使用 POST 模式：pageExecute($request, 'POST')
+$response = $aop->pageExecute($request, 'POST');
+
+// pageExecute 返回的是 HTML 表单字符串，前端需要渲染并自动提交
+echo $response;
+```
+
+> **⚠️ 关键注意事项：**
+> 1. 必须使用 `pageExecute()` 方法，不能使用 `execute()` 方法
+> 2. 必须使用 POST 模式：`$aop->pageExecute($request, 'POST')`
+> 3. 返回的 HTML 需要前端渲染并自动提交，禁止直接在服务端 redirect
+> 4. PHP 使用 PKCS#1 格式私钥，Java 使用 PKCS#8 格式，请勿混用
+
+## 响应示例
+### 正常示例
+```html
+<form name="punchout_form" method="post" action="https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.page.pay&format=json&sign=SIGN_PLACEHOLDER&version=1.0&app_id=20190xxxxxx&sign_type=RSA2&timestamp=2014-07-24+03%3A07%3A50">
+<input type="hidden" name="biz_content" value="{&quot;out_trade_no&quot;:&quot;MERCHANT_ORDER_NO_PLACEHOLDER&quot;,&quot;total_amount&quot;:&quot;0.01&quot;,&quot;subject&quot;:&quot;测试商品&quot;,&quot;product_code&quot;:&quot;FAST_INSTANT_TRADE_PAY&quot;}">
+<input type="submit" value="立即支付" style="display:none" >
+</form>
+<script>document.forms[0].submit();</script>
+```

package/skill-pre/references/integration/modules/code-examples/php/3-APP/346/224/257/344/273/230/APP/346/224/257/344/273/230/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,110 @@
+# APP 支付接口 - PHP 示例
+
+## 请求示例
+
+```php
+<?php
+require_once '../aop/AopClient.php';
+require_once '../aop/AopCertClient.php';
+require_once '../aop/AopCertification.php';
+require_once '../aop/AlipayConfig.php';
+require_once '../aop/request/AlipayTradeAppPayRequest.php';
+
+// 初始化SDK
+$alipayClient = new AopClient(getAlipayConfig());
+// 构造请求参数以调用接口
+$request = new AlipayTradeAppPayRequest();
+$notifyUrl = trim(getenv('ALIPAY_NOTIFY_URL') ?: '');
+if ($notifyUrl !== '') {
+    $request->setNotifyUrl($notifyUrl);  // 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 null、空字符串或占位 URL
+}
+$model = array();
+
+// 设置商户订单号
+$model['out_trade_no'] = "MERCHANT_ORDER_NO_PLACEHOLDER";
+
+// 设置订单总金额
+$model['total_amount'] = "9.00";
+
+// 设置订单标题
+$model['subject'] = "大乐透";
+
+// 设置产品码
+$model['product_code'] = "QUICK_MSECURITY_PAY";
+
+// 设置订单包含的商品列表信息
+$goodsDetail = array();
+$goodsDetail0 = array();
+$goodsDetail0['goods_name'] = "ipad";
+$goodsDetail0['alipay_goods_id'] = "20010001";
+$goodsDetail0['quantity'] = 1;
+$goodsDetail0['price'] = "2000";
+$goodsDetail0['goods_id'] = "apple-01";
+$goodsDetail0['goods_category'] = "34543238";
+$goodsDetail0['categories_tree'] = "124868003|126232002|126252004";
+$goodsDetail0['show_url'] = "http://www.alipay.com/xxx.jpg";
+$goodsDetail[] = $goodsDetail0;
+$model['goods_detail'] = $goodsDetail;
+
+// 设置订单绝对超时时间
+$model['time_expire'] = "2016-12-31 10:05:00";
+
+// 设置业务扩展参数
+$extendParams = array();
+$extendParams['sys_service_provider_id'] = "<SYS_SERVICE_PROVIDER_ID>";
+$extendParams['hb_fq_seller_percent'] = "100";
+$extendParams['hb_fq_num'] = "3";
+$extendParams['industry_reflux_info'] = "{\"scene_code\":\"metro_tradeorder\",\"channel\":\"xxxx\",\"scene_data\":{\"asset_name\":\"ALIPAY\"}}";
+$extendParams['royalty_freeze'] = "true";
+$extendParams['card_type'] = "S0JP0000";
+$model['extend_params'] = $extendParams;
+
+// 设置公用回传参数
+$model['passback_params'] = "merchantBizType%3d3C%26merchantBizNo%3dMERCHANT_BIZ_NO_PLACEHOLDER";
+
+// 设置商户的原始订单号
+$model['merchant_order_no'] = "MERCHANT_ORDER_NO_PLACEHOLDER";
+
+// 设置外部指定买家
+$extUserInfo = array();
+$extUserInfo['cert_type'] = "IDENTITY_CARD";
+$extUserInfo['cert_no'] = "<CERT_NO>";
+$extUserInfo['mobile'] = "<MOBILE>";
+$extUserInfo['name'] = "李明";
+$extUserInfo['min_age'] = "18";
+$extUserInfo['need_check_info'] = "F";
+$extUserInfo['identity_hash'] = "<IDENTITY_HASH>";
+$model['ext_user_info'] = $extUserInfo;
+
+// 设置通知参数选项
+$queryOptions = array();
+$queryOptions[] = "hyb_amount";
+$queryOptions[] = "enterprise_pay_info";
+$model['query_options'] = $queryOptions;
+
+$request->setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE));
+// 如果是第三方代调用模式，请设置app_auth_token（应用授权令牌）
+$orderStr = $alipayClient->sdkExecute($request, "<-- 请填写应用授权令牌 -->");
+echo $orderStr;
+
+function getAlipayConfig()
+{
+    $privateKey  = '<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->';
+    $alipayPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->';
+    $alipayConfig = new AlipayConfig();
+    $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do');
+    $alipayConfig->setAppId('<-- 请填写您的AppId，例如：20190xxxxxx -->');
+    $alipayConfig->setPrivateKey($privateKey);
+    $alipayConfig->setFormat('json');
+    $alipayConfig->setAlipayPublicKey($alipayPublicKey);
+    $alipayConfig->setCharset('UTF-8');
+    $alipayConfig->setSignType('RSA2');
+    return $alipayConfig;
+}
+```
+
+## 响应示例
+### 正常示例
+```
+app_id=20190xxxxxx&biz_content=%7B%22time_expire%22%3A%222016-12-31+10%3A05%3A00%22%2C%22extend_params%22%3A%22%22%2C%22query_options%22%3A%22%5B%5C%22hyb_amount%5C%22%2C%5C%22enterprise_pay_info%5C%22%5D%22%2C%22subject%22%3A%22%E5%A4%A7%E4%B9%90%E9%80%8F%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22body%22%3A%22Iphone6+16G%22%2C%22passback_params%22%3A%22merchantBizType%253d3C%2526merchantBizNo%253dMERCHANT_BIZ_NO_PLACEHOLDER%22%2C%22specified_channel%22%3A%22pcredit%22%2C%22goods_detail%22%3A%22%22%2C%22merchant_order_no%22%3A%22MERCHANT_ORDER_NO_PLACEHOLDER%22%2C%22enable_pay_channels%22%3A%22pcredit%2CmoneyFund%2CdebitCardExpress%22%2C%22out_trade_no%22%3A%22MERCHANT_ORDER_NO_PLACEHOLDER%22%2C%22ext_user_info%22%3A%22%22%2C%22total_amount%22%3A%229.00%22%2C%22timeout_express%22%3A%2290m%22%2C%22disable_pay_channels%22%3A%22pcredit%2CmoneyFund%2CdebitCardExpress%22%2C%22agreement_sign_params%22%3A%22%22%7D&charset=UTF-8&format=json&method=alipay.trade.app.pay&sign=SIGN_PLACEHOLDER&sign_type=RSA2&timestamp=2014-07-24+03%3A07%3A50&version=1.0
+```