@alipay/alipay-aipay 1.2.2 → 1.4.9

package/skill/references/integration/modules/code-examples/java/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

@@ -1,4 +1,4 @@
-# APP支付接口 - Java 示例
+# APP 支付接口 - Java 示例
 
 ## 请求示例
 
@@ -29,6 +29,10 @@ public class AlipayTradeAppPay {
 
         // 构造请求参数以调用接口
         AlipayTradeAppPayRequest request = new AlipayTradeAppPayRequest();
+        String notifyUrl = System.getenv("ALIPAY_NOTIFY_URL");
+        if (notifyUrl != null && !notifyUrl.isBlank()) {
+            request.setNotifyUrl(notifyUrl.trim());  // 真实生产或公网联调时传入；本地没有公网 HTTPS notifyUrl 时不要调用 setNotifyUrl(null/空字符串/占位 URL)
+        }
         AlipayTradeAppPayModel model = new AlipayTradeAppPayModel();
         
         // 设置商户订单号
@@ -132,4 +136,3 @@ public class AlipayTradeAppPay {
 ```
 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
 ```
-

package/skill/references/integration/modules/code-examples/java/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemoController.java

@@ -107,7 +107,9 @@ public class A2MPaymentDemoController {
      */
     private static AlipayConfig getAlipayConfig() {
         AlipayConfig alipayConfig = new AlipayConfig();
-        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
+        // 默认用于本 Skill 的快速沙箱联调；生产部署时显式设置 ALIPAY_GATEWAY=https://openapi.alipay.com/gateway.do
+        alipayConfig.setServerUrl(System.getenv().getOrDefault(
+            "ALIPAY_GATEWAY", "https://openapi-sandbox.dl.alipaydev.com/gateway.do"));
         alipayConfig.setAppId("<APP_ID>");
         alipayConfig.setPrivateKey("<APP_PRIVATE_KEY>"); // 请填写您的应用私钥
         alipayConfig.setFormat("json");

package/skill/references/integration/modules/code-examples/nodejs/1-/351/200/232/347/224/250/346/216/245/345/217/243//345/274/202/346/255/245/351/200/232/347/237/245/345/244/204/347/220/206/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,135 @@
+# 异步通知处理 - Node.js 示例
+
+适用产品：网站支付、APP 支付。按量付费不使用异步通知。
+
+```javascript
+const express = require("express");
+
+// 支付宝异步通知是 application/x-www-form-urlencoded 表单，不能用 JSON parser 代替。
+// createAlipayNotifyRouter 依赖项目里的真实 SDK 工厂、支付配置、订单仓储和通知事件仓储。
+// 生产环境必须用持久化订单表和通知事件表做幂等；内存 Map 只能用于非生产 demo。
+function createAlipayNotifyRouter(deps) {
+  const router = express.Router();
+  router.use(express.urlencoded({ extended: false }));
+
+  router.post("/alipay/notify", async (req, res) => {
+    const params = { ...req.body };
+
+    try {
+      const config = await deps.paymentConfigRepository.findByAppId(params.app_id);
+      if (!config) {
+        return fail(res, deps, "alipay notify app config not found", params);
+      }
+
+      const alipaySdk = deps.alipaySdkFactory.create(config);
+      if (!(await verifyNotifyWithAlipaySdk(params, alipaySdk))) {
+        return fail(res, deps, "alipay notify signature check failed", params);
+      }
+
+      const order = await deps.orderRepository.findByOutTradeNo(params.out_trade_no);
+      if (!order || !businessFieldsMatch(order, params, config)) {
+        return fail(res, deps, "alipay notify business check failed", params);
+      }
+
+      const inserted = await deps.notifyEventRepository.insertOnce({
+        notifyId: params.notify_id,
+        tradeNo: params.trade_no,
+        outTradeNo: params.out_trade_no,
+        tradeStatus: params.trade_status,
+        rawParams: params,
+      });
+      if (!inserted) {
+        return res.type("text/plain").send("success");
+      }
+
+      if (isPaidTradeNotification(params)) {
+        await deps.orderRepository.markPaidIdempotently(order.outTradeNo, params.trade_no, params);
+      } else {
+        await deps.orderRepository.recordNonPaidTradeEvent(order.outTradeNo, params.trade_status, params);
+      }
+
+      return res.type("text/plain").send("success");
+    } catch (error) {
+      safeLogNotifyError(deps, "alipay notify unexpected exception", params);
+      return res.type("text/plain").send("fail");
+    }
+  });
+
+  return router;
+}
+
+async function verifyNotifyWithAlipaySdk(params, alipaySdk) {
+  // 落地前先查看目标项目 node_modules/alipay-sdk 的 package.json 和 .d.ts。
+  // 如果当前版本类型定义确认存在 checkNotifySignV2(params)，按当前 SDK 实际 API 调用。
+  if (typeof alipaySdk.checkNotifySignV2 !== "function") {
+    throw new Error("current alipay-sdk does not expose checkNotifySignV2; confirm SDK types before coding");
+  }
+  return await Promise.resolve(alipaySdk.checkNotifySignV2(params));
+}
+
+function businessFieldsMatch(order, params, config) {
+  return params.app_id === config.appId
+    && params.out_trade_no === order.outTradeNo
+    && amountEquals(order.totalAmount, params.total_amount)
+    && expectedSellerMatches(config, params.seller_id, params.seller_email);
+}
+
+function isPaidTradeNotification(params) {
+  const paidStatus = params.trade_status === "TRADE_SUCCESS" || params.trade_status === "TRADE_FINISHED";
+  return paidStatus && !params.out_biz_no && !params.gmt_refund && !params.refund_fee;
+}
+
+function amountEquals(expected, actual) {
+  const expectedAmount = normalizeAmountText(expected);
+  const actualAmount = normalizeAmountText(actual);
+  return expectedAmount !== null && expectedAmount === actualAmount;
+}
+
+// 返回“元”为单位、保留两位小数的金额文本，例如 88.00；不要用浮点数直接比较金额。
+function normalizeAmountText(value) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  const match = text.match(/^(\d+)(?:\.(\d{1,2}))?$/);
+  if (!match) return null;
+  return `${BigInt(match[1]).toString()}.${(match[2] || "").padEnd(2, "0")}`;
+}
+
+function expectedSellerMatches(config, sellerId, sellerEmail) {
+  const expectedSellerId = config.sellerId;
+  const expectedSellerEmail = config.sellerEmail;
+  return Boolean(
+    (expectedSellerId && sellerId === expectedSellerId)
+      || (expectedSellerEmail && sellerEmail === expectedSellerEmail)
+  );
+}
+
+function fail(res, deps, message, params) {
+  safeLogNotifyError(deps, message, params);
+  return res.type("text/plain").send("fail");
+}
+
+function safeLogNotifyError(deps, message, params) {
+  try {
+    deps.logger.warn(message, sanitizeNotifyParams(params));
+  } catch (error) {
+    // 日志失败不能影响支付宝收到纯文本 fail。
+  }
+}
+
+function sanitizeNotifyParams(params) {
+  const { sign, ...safeParams } = params;
+  return safeParams;
+}
+
+module.exports = { createAlipayNotifyRouter };
+```
+
+要点：
+
+- `notify_url` 路由必须使用表单解析中间件，不要用 JSON parser 读取支付宝通知。
+- 验签必须调用当前项目支付宝 SDK 的实际验签 API；Node.js 落地前先查目标项目 `alipay-sdk` 类型定义确认 `checkNotifySignV2(params)` 是否存在。
+- `app_id`、`seller_id` / `seller_email` 从运行时支付配置校验，不从订单对象默认取值。
+- 金额校验使用“元”为单位的两位小数字符串或项目定点数工具，不要用浮点数直接比较。
+- 只有付款成功状态且不是退款、关单、分账等事件时，才认定付款成功。
+- 内存订单或内存幂等只能用于非生产 demo，生产必须使用持久化订单表和通知事件表。
+- 处理成功后返回纯文本 `success`；异常、验签失败或业务校验失败返回 `fail`。

package/skill/references/integration/modules/code-examples/nodejs/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

@@ -18,20 +18,26 @@ const alipaySdk = new AlipaySdk({
 // ⚠️ 网站支付必须使用 pageExec() 方法，不能使用 exec()
 // ⚠️ pageExec() 第二个参数必须传 'POST'
 // ⚠️ notifyUrl 在真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+// ⚠️ 本地没有公网 HTTPS notifyUrl 时，直接省略 notifyUrl，不要向 SDK 传 undefined、空字符串或占位 URL
 // ⚠️ returnUrl 默认传入，仅在用户明确关闭同步回跳时省略
+const notifyUrl = (process.env.ALIPAY_NOTIFY_URL || "").trim();
+const requestOptions = {
+  returnUrl: "https://your-domain.com/return", // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
+  bizContent: {
+    out_trade_no: "MERCHANT_ORDER_NO_PLACEHOLDER",         // 商户订单号，必填
+    total_amount: "88.88",                      // 订单总金额，必填，单位为元，精确到小数点后两位
+    subject: "Iphone6 16G",                     // 订单标题，必填
+    product_code: "FAST_INSTANT_TRADE_PAY",     // 网站支付固定值，必填
+  },
+};
+if (notifyUrl) {
+  requestOptions.notifyUrl = notifyUrl;
+}
+
 const result = alipaySdk.pageExec(
   "alipay.trade.page.pay",
   "POST",
-  {
-    notifyUrl: "https://your-domain.com/notify", // 真实生产或公网联调时传入；本地生产参数验收模式可临时不传
-    returnUrl: "https://your-domain.com/return", // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
-    bizContent: {
-      out_trade_no: "MERCHANT_ORDER_NO_PLACEHOLDER",         // 商户订单号，必填
-      total_amount: "88.88",                      // 订单总金额，必填，单位为元，精确到小数点后两位
-      subject: "Iphone6 16G",                     // 订单标题，必填
-      product_code: "FAST_INSTANT_TRADE_PAY",     // 网站支付固定值，必填
-    },
-  }
+  requestOptions
 );
 
 // pageExec 返回的是 HTML 表单字符串，前端需要渲染并自动提交

package/skill/references/integration/modules/code-examples/nodejs/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

@@ -1,4 +1,4 @@
-# APP支付接口 - Node.js 示例
+# APP 支付接口 - Node.js 示例
 
 ## 请求示例
 
@@ -12,7 +12,10 @@ const alipaySdk = new AlipaySdk({
   gateway: "https://openapi.alipay.com/gateway.do",
   appAuthToken: "<-- 请填写应用授权令牌 -->",
 });
-const result = await alipaySdk.sdkExec("alipay.trade.app.pay", {
+
+// 真实生产或公网联调时传入 notifyUrl；本地没有公网 HTTPS notifyUrl 时直接省略，不要向 SDK 传 undefined、空字符串或占位 URL。
+const notifyUrl = (process.env.ALIPAY_NOTIFY_URL || "").trim();
+const requestOptions = {
   bizContent: {
     out_trade_no: "MERCHANT_ORDER_NO_PLACEHOLDER",
     total_amount: "9.00",
@@ -54,7 +57,11 @@ const result = await alipaySdk.sdkExec("alipay.trade.app.pay", {
     },
     query_options: ["hyb_amount", "enterprise_pay_info"],
   },
-});
+};
+if (notifyUrl) {
+  requestOptions.notifyUrl = notifyUrl;
+}
+const result = await alipaySdk.sdkExec("alipay.trade.app.pay", requestOptions);
 ```
 
 ## 响应示例
@@ -62,4 +69,3 @@ const result = await alipaySdk.sdkExec("alipay.trade.app.pay", {
 ```
 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
 ```
-

package/skill/references/integration/modules/code-examples/nodejs/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.js

@@ -30,7 +30,8 @@ const CONFIG = {
     appId: '<APP_ID>', // 运行时映射沙箱 appId
     privateKey: '<APP_PRIVATE_KEY>', // 运行时映射 appPrivatePkcsKey（PKCS#1）
     alipayPublicKey: '<ALIPAY_PUBLIC_KEY>', // 运行时映射 alipayPublicKey
-    gateway: 'https://openapi.alipay.com/gateway.do',
+    // 默认用于本 Skill 的快速沙箱联调；生产部署时显式设置 ALIPAY_GATEWAY=https://openapi.alipay.com/gateway.do
+    gateway: process.env.ALIPAY_GATEWAY || 'https://openapi-sandbox.dl.alipaydev.com/gateway.do',
     sellerId: '<SELLER_ID_2088>', // 商户 ID（2088 格式）
     serviceId: 'api_mock_service_id', // 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
     merchantPrivateKey: '<APP_PRIVATE_KEY>' // 与 privateKey 使用同一运行时配置，用于商家签名

package/skill/references/integration/modules/code-examples/php/1-/351/200/232/347/224/250/346/216/245/345/217/243//345/274/202/346/255/245/351/200/232/347/237/245/345/244/204/347/220/206/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,157 @@
+# 异步通知处理 - PHP 示例
+
+适用产品：网站支付、APP 支付。按量付费不使用异步通知。
+
+```php
+<?php
+
+// 支付宝通知是 POST 表单，不是 JSON。
+// $deps 接入项目真实 SDK 验签适配器、支付配置、订单仓储、通知事件仓储和脱敏日志。
+function handleAlipayNotify(array $params, array $deps): void
+{
+    try {
+        $config = $deps['paymentConfigRepository']->findByAppId($params['app_id'] ?? '');
+        if ($config === null) {
+            fail($deps, 'alipay notify app config not found', $params);
+        }
+
+        if (!verifyNotifyWithAlipaySdk($params, $deps['alipayNotifyVerifier'], $config)) {
+            fail($deps, 'alipay notify signature check failed', $params);
+        }
+
+        $order = $deps['orderRepository']->findByOutTradeNo($params['out_trade_no'] ?? '');
+        if ($order === null || !businessFieldsMatch($order, $params, $config)) {
+            fail($deps, 'alipay notify business check failed', $params);
+        }
+
+        $inserted = $deps['notifyEventRepository']->insertOnce([
+            'notify_id' => $params['notify_id'] ?? '',
+            'trade_no' => $params['trade_no'] ?? '',
+            'out_trade_no' => $params['out_trade_no'] ?? '',
+            'trade_status' => $params['trade_status'] ?? '',
+            'raw_params' => $params,
+        ]);
+        if (!$inserted) {
+            respondPlainText('success');
+        }
+
+        if (isPaidTradeNotification($params)) {
+            $deps['orderRepository']->markPaidIdempotently($order['out_trade_no'], $params['trade_no'] ?? '', $params);
+        } else {
+            $deps['orderRepository']->recordNonPaidTradeEvent($order['out_trade_no'], $params['trade_status'] ?? '', $params);
+        }
+
+        respondPlainText('success');
+    } catch (Throwable $e) {
+        safeLogNotifyError($deps, 'alipay notify unexpected exception', $params);
+        respondPlainText('fail');
+    }
+}
+
+function businessFieldsMatch(array $order, array $params, array $config): bool
+{
+    return ($params['app_id'] ?? '') === ($config['app_id'] ?? '')
+        && ($params['out_trade_no'] ?? '') === $order['out_trade_no']
+        && amountEquals($order['total_amount'], $params['total_amount'] ?? null)
+        && expectedSellerMatches($config, $params['seller_id'] ?? null, $params['seller_email'] ?? null);
+}
+
+function isPaidTradeNotification(array $params): bool
+{
+    $paidStatus = ($params['trade_status'] ?? '') === 'TRADE_SUCCESS'
+        || ($params['trade_status'] ?? '') === 'TRADE_FINISHED';
+    return $paidStatus
+        && empty($params['out_biz_no'])
+        && empty($params['gmt_refund'])
+        && empty($params['refund_fee']);
+}
+
+function amountEquals($expected, $actual): bool
+{
+    if ($actual === null) {
+        return false;
+    }
+    $expectedAmount = normalizeAmountText($expected);
+    $actualAmount = normalizeAmountText($actual);
+    return $expectedAmount !== null && $expectedAmount === $actualAmount;
+}
+
+function normalizeAmountText($value): ?string
+{
+    $text = trim((string) $value);
+    if (!preg_match('/^(\d+)(?:\.(\d{1,2}))?$/', $text, $matches)) {
+        return null;
+    }
+    $yuan = ltrim($matches[1], '0');
+    return ($yuan === '' ? '0' : $yuan) . '.' . str_pad($matches[2] ?? '', 2, '0');
+}
+
+function expectedSellerMatches(array $config, ?string $sellerId, ?string $sellerEmail): bool
+{
+    $expectedSellerId = firstNonBlank($config['seller_id'] ?? null, null);
+    $expectedSellerEmail = firstNonBlank($config['seller_email'] ?? null, null);
+    return ($expectedSellerId !== null && $sellerId === $expectedSellerId)
+        || ($expectedSellerEmail !== null && $sellerEmail === $expectedSellerEmail);
+}
+
+function firstNonBlank(?string $primary, ?string $fallback): ?string
+{
+    if ($primary !== null && trim($primary) !== '') {
+        return $primary;
+    }
+    if ($fallback !== null && trim($fallback) !== '') {
+        return $fallback;
+    }
+    return null;
+}
+
+function verifyNotifyWithAlipaySdk(array $params, object $verifier, array $config): bool
+{
+    // 使用当前项目已安装的支付宝 SDK 验签能力校验 $params['sign']。
+    // $verifier->verify($params, $config) 必须封装目标项目当前 SDK 实际通知验签 API；落地前先查已安装包文档或类型定义，不能手写临时 RSA 验签。
+    return $verifier->verify($params, $config);
+}
+
+function fail(array $deps, string $message, array $params): void
+{
+    safeLogNotifyError($deps, $message, $params);
+    respondPlainText('fail');
+}
+
+function respondPlainText(string $body): void
+{
+    header('Content-Type: text/plain; charset=UTF-8');
+    echo $body;
+    exit;
+}
+
+function safeLogNotifyError(array $deps, string $message, array $params): void
+{
+    try {
+        if (isset($deps['logger'])) {
+            $deps['logger']->warning($message, sanitizeNotifyParams($params));
+        }
+    } catch (Throwable $e) {
+        // 日志失败不能影响支付宝收到纯文本 fail。
+    }
+}
+
+function sanitizeNotifyParams(array $params): array
+{
+    unset($params['sign']);
+    return $params;
+}
+
+// 在项目路由入口中由 DI 容器提供 $deps 后调用：
+// handleAlipayNotify($_POST, $deps);
+```
+
+要点：
+
+- 支付宝通知是 POST 表单，验签前必须保留完整 `$_POST` 参数。
+- 验签必须调用当前项目支付宝 SDK 的实际验签 API，验签前不得丢字段或改值。
+- `app_id`、`seller_id` / `seller_email` 从运行时支付配置校验，不从订单对象默认取值。
+- 金额校验使用字符串或定点数规范化，不要用浮点数直接比较，也不要默认依赖未安装的 PHP 扩展。
+- 只有付款成功状态且不是退款、关单、分账等事件时，才认定付款成功。
+- 内存订单或内存幂等只能用于非生产 demo，生产必须使用持久化订单表和通知事件表。
+- 处理成功后返回纯文本 `success`；异常、验签失败或业务校验失败返回 `fail`。

package/skill/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

@@ -20,7 +20,10 @@ $aop->signType = 'RSA2';
 
 // 构造请求参数
 $request = new AlipayTradePagePayRequest();
-$request->setNotifyUrl('https://your-domain.com/notify');  // 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+$notifyUrl = trim(getenv('ALIPAY_NOTIFY_URL') ?: '');
+if ($notifyUrl !== '') {
+    $request->setNotifyUrl($notifyUrl);  // 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 null、空字符串或占位 URL
+}
 $request->setReturnUrl('https://your-domain.com/return');  // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
 $bizContent = [

package/skill/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

@@ -1,4 +1,4 @@
-# APP支付接口 - PHP 示例
+# APP 支付接口 - PHP 示例
 
 ## 请求示例
 
@@ -14,6 +14,10 @@ require_once '../aop/request/AlipayTradeAppPayRequest.php';
 $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();
 
 // 设置商户订单号
@@ -104,4 +108,3 @@ function getAlipayConfig()
 ```
 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
 ```
-

package/skill/references/integration/modules/code-examples/php/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.php

@@ -22,7 +22,8 @@ define('ALIPAY_CONFIG', [
     'appId' => '<APP_ID>',
     'privateKey' => '<APP_PRIVATE_KEY>', // 请填写您的应用私钥（PKCS#1 格式）
     'alipayPublicKey' => '<ALIPAY_PUBLIC_KEY>', // 请填写您的支付宝公钥
-    'gateway' => 'https://openapi.alipay.com/gateway.do',
+    // 默认用于本 Skill 的快速沙箱联调；生产部署时设置 ALIPAY_GATEWAY=https://openapi.alipay.com/gateway.do
+    'gateway' => getenv('ALIPAY_GATEWAY') ?: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do',
     'sellerId' => '<SELLER_ID_2088>', // 商户 ID（2088 格式）
     'serviceId' => 'api_mock_service_id', // 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
     'merchantPrivateKey' => '<APP_PRIVATE_KEY>' // 请填写您的应用私钥（用于商家签名）

package/skill/references/integration/modules/code-examples/python/1-/351/200/232/347/224/250/346/216/245/345/217/243//345/274/202/346/255/245/351/200/232/347/237/245/345/244/204/347/220/206/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,128 @@
+# 异步通知处理 - Python 示例
+
+适用产品：网站支付、APP 支付。按量付费不使用异步通知。
+
+```python
+import re
+from flask import Blueprint, Response, request
+
+
+def create_alipay_notify_blueprint(deps):
+    """deps 接入项目真实 SDK 验签适配器、支付配置、订单仓储、通知事件仓储和脱敏日志。"""
+    blueprint = Blueprint("alipay_notify", __name__)
+
+    @blueprint.post("/alipay/notify")
+    def alipay_notify():
+        params = {}
+        try:
+            params = request.form.to_dict(flat=True)
+            config = deps["payment_config_repository"].find_by_app_id(params.get("app_id"))
+            if config is None:
+                return fail(deps, "alipay notify app config not found", params)
+
+            if not verify_notify_with_alipay_sdk(params, deps["alipay_notify_verifier"], config):
+                return fail(deps, "alipay notify signature check failed", params)
+
+            order = deps["order_repository"].find_by_out_trade_no(params.get("out_trade_no"))
+            if order is None or not business_fields_match(order, params, config):
+                return fail(deps, "alipay notify business check failed", params)
+
+            inserted = deps["notify_event_repository"].insert_once(
+                notify_id=params.get("notify_id"),
+                trade_no=params.get("trade_no"),
+                out_trade_no=params.get("out_trade_no"),
+                trade_status=params.get("trade_status"),
+                raw_params=params,
+            )
+            if not inserted:
+                return Response("success", mimetype="text/plain")
+
+            if is_paid_trade_notification(params):
+                deps["order_repository"].mark_paid_idempotently(order["out_trade_no"], params.get("trade_no"), params)
+            else:
+                deps["order_repository"].record_non_paid_trade_event(order["out_trade_no"], params.get("trade_status"), params)
+
+            return Response("success", mimetype="text/plain")
+        except Exception:
+            safe_log_notify_error(deps, "alipay notify unexpected exception", params)
+            return Response("fail", mimetype="text/plain")
+
+    return blueprint
+
+
+def business_fields_match(order, params, config):
+    return (
+        params.get("app_id") == config["app_id"]
+        and params.get("out_trade_no") == order["out_trade_no"]
+        and amount_equals(order["total_amount"], params.get("total_amount"))
+        and expected_seller_matches(config, params.get("seller_id"), params.get("seller_email"))
+    )
+
+
+def is_paid_trade_notification(params):
+    paid_status = params.get("trade_status") in ("TRADE_SUCCESS", "TRADE_FINISHED")
+    return paid_status and not params.get("out_biz_no") and not params.get("gmt_refund") and not params.get("refund_fee")
+
+
+def amount_equals(expected, actual):
+    expected_amount = normalize_amount_text(expected)
+    actual_amount = normalize_amount_text(actual)
+    return expected_amount is not None and expected_amount == actual_amount
+
+
+def normalize_amount_text(value):
+    if value is None:
+        return None
+    match = re.fullmatch(r"(\d+)(?:\.(\d{1,2}))?", str(value).strip())
+    if not match:
+        return None
+    return f"{int(match.group(1))}.{(match.group(2) or '').ljust(2, '0')}"
+
+
+def expected_seller_matches(config, seller_id, seller_email):
+    expected_seller_id = config.get("seller_id")
+    expected_seller_email = config.get("seller_email")
+    return (
+        bool(expected_seller_id and seller_id == expected_seller_id)
+        or bool(expected_seller_email and seller_email == expected_seller_email)
+    )
+
+
+def verify_notify_with_alipay_sdk(params, verifier, config):
+    """
+    使用当前项目已安装的支付宝 SDK 验签能力校验 params["sign"]。
+    verifier.verify(params, config) 必须封装目标项目当前 SDK 实际通知验签 API；落地前先查已安装包文档或类型定义，不能手写临时 RSA 验签。
+    """
+    return verifier.verify(params, config)
+
+
+def fail(deps, message, params):
+    safe_log_notify_error(deps, message, params)
+    return Response("fail", mimetype="text/plain")
+
+
+def safe_log_notify_error(deps, message, params):
+    try:
+        logger = deps.get("logger")
+        if logger is not None:
+            logger.warning(message, extra={"alipay_notify": sanitize_notify_params(params)})
+    except Exception:
+        # 日志失败不能影响支付宝收到纯文本 fail。
+        pass
+
+
+def sanitize_notify_params(params):
+    safe_params = dict(params)
+    safe_params.pop("sign", None)
+    return safe_params
+```
+
+要点：
+
+- 支付宝通知是 POST 表单，不能用 JSON body 解析。
+- 验签必须调用当前项目支付宝 SDK 的实际验签 API，验签前不得丢字段或改值。
+- `app_id`、`seller_id` / `seller_email` 从运行时支付配置校验，不从订单对象默认取值。
+- 金额校验使用字符串规范化、`Decimal` 或项目定点数工具，不要用浮点数直接比较。
+- 只有付款成功状态且不是退款、关单、分账等事件时，才认定付款成功。
+- 内存订单或内存幂等只能用于非生产 demo，生产必须使用持久化订单表和通知事件表。
+- 处理成功后返回纯文本 `success`；异常、验签失败或业务校验失败返回 `fail`。

package/skill/references/integration/modules/code-examples/python/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

@@ -3,6 +3,7 @@
 ## 请求示例
 
 ```python
+import os
 from alipay.aop.api.AlipayClientConfig import AlipayClientConfig
 from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
 from alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest
@@ -20,7 +21,9 @@ config.sign_type = "RSA2"
 client = DefaultAlipayClient(alipay_client_config=config)
 
 request = AlipayTradePagePayRequest()
-request.notify_url = "https://your-domain.com/notify"  # 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+notify_url = os.getenv("ALIPAY_NOTIFY_URL", "").strip()
+if notify_url:
+    request.notify_url = notify_url  # 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 None、空字符串或占位 URL
 request.return_url = "https://your-domain.com/return"  # 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
 model = AlipayTradePagePayModel()

package/skill/references/integration/modules/code-examples/python/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

@@ -1,9 +1,10 @@
-# APP支付接口 - Python 示例
+# APP 支付接口 - Python 示例
 
 ## 请求示例
 
 ```python
 import json
+import os
 from alipay.aop.api.AlipayClientConfig import AlipayClientConfig
 from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
 from alipay.aop.api.request.AlipayTradeAppPayRequest import AlipayTradeAppPayRequest
@@ -21,6 +22,9 @@ client = DefaultAlipayClient(alipay_client_config=config)
 
 # 构造请求参数以调用接口
 request = AlipayTradeAppPayRequest()
+notify_url = os.getenv("ALIPAY_NOTIFY_URL", "").strip()
+if notify_url:
+    request.notify_url = notify_url  # 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 None、空字符串或占位 URL
 model = AlipayTradeAppPayModel()
 
 model.out_trade_no = "MERCHANT_ORDER_NO_PLACEHOLDER"

package/skill/references/integration/modules/code-examples/python/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.py

@@ -21,9 +21,10 @@ pip install flask alipay-sdk-python pycryptodome
 不能直接使用 dict 赋值给 biz_model，因为 SDK 会调用 to_alipay_dict() 方法。
 """
 
+import base64
 import json
+import os
 import time
-import base64
 from datetime import datetime, timedelta, timezone
 from urllib.parse import quote, unquote
 from Crypto.Signature import pkcs1_15
@@ -44,7 +45,8 @@ ALIPAY_CONFIG = {
     'appId': '<APP_ID>',
     'privateKey': '<APP_PRIVATE_KEY>',  # 请填写您的应用私钥（PKCS#1 格式）
     'alipayPublicKey': '<ALIPAY_PUBLIC_KEY>',  # 请填写您的支付宝公钥
-    'gateway': 'https://openapi.alipay.com/gateway.do',
+    # 默认用于本 Skill 的快速沙箱联调；生产部署时显式设置为 https://openapi.alipay.com/gateway.do
+    'gateway': os.environ.get('ALIPAY_GATEWAY', 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'),
     'sellerId': '<SELLER_ID_2088>',  # 商户 ID（2088 格式）
     'serviceId': 'api_mock_service_id',  # 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
     'merchantPrivateKey': '<APP_PRIVATE_KEY>'  # 请填写您的应用私钥（用于商家签名）