@alipay/alipay-aipay 1.2.2 → 1.5.0

package/skill/references/integration/modules/code-examples/java/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,184 @@
+# 异步通知处理 - Java 示例
+
+适用产品：AI 网页应用收款、AI 移动应用收款。AI 按量付费不使用异步通知。
+
+```java
+import com.alipay.api.internal.util.AlipaySignature;
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.ResponseBody;
+
+import java.math.BigDecimal;
+import java.util.HashMap;
+import java.util.Map;
+
+public class AlipayNotifyController {
+    private static final String CHARSET = "UTF-8";
+    private final PaymentConfigRepository paymentConfigRepository;
+    private final OrderRepository orderRepository;
+    private final NotifyEventRepository notifyEventRepository;
+    private final NotifyLogger notifyLogger;
+
+    public AlipayNotifyController(
+        PaymentConfigRepository paymentConfigRepository,
+        OrderRepository orderRepository,
+        NotifyEventRepository notifyEventRepository,
+        NotifyLogger notifyLogger
+    ) {
+        this.paymentConfigRepository = paymentConfigRepository;
+        this.orderRepository = orderRepository;
+        this.notifyEventRepository = notifyEventRepository;
+        this.notifyLogger = notifyLogger;
+    }
+
+    @PostMapping(value = "/alipay/notify", produces = "text/plain;charset=UTF-8")
+    @ResponseBody
+    public String handleAlipayNotify(HttpServletRequest request) {
+        Map<String, String> params = new HashMap<>();
+        try {
+            params = collectFormParams(request);
+            AlipayNotifyConfig config = paymentConfigRepository.findByAppId(params.get("app_id"));
+
+            if (config == null || !verifyNotifyWithAlipaySdk(params, config)) {
+                return fail("alipay notify signature check failed", params);
+            }
+
+            MerchantOrder order = orderRepository.findByOutTradeNo(params.get("out_trade_no"));
+            if (order == null || !businessFieldsMatch(order, params, config)) {
+                return fail("alipay notify business check failed", params);
+            }
+
+            boolean inserted = notifyEventRepository.insertOnce(
+                params.get("notify_id"),
+                params.get("trade_no"),
+                params.get("out_trade_no"),
+                params.get("trade_status"),
+                params
+            );
+            if (!inserted) {
+                return "success";
+            }
+
+            if (isPaidTradeNotification(params)) {
+                orderRepository.markPaidIdempotently(order.outTradeNo(), params.get("trade_no"), params);
+            } else {
+                orderRepository.recordNonPaidTradeEvent(order.outTradeNo(), params.get("trade_status"), params);
+            }
+
+            return "success";
+        } catch (Exception e) {
+            safeLogNotifyError("alipay notify unexpected exception", params);
+            return "fail";
+        }
+    }
+
+    private static Map<String, String> collectFormParams(HttpServletRequest request) {
+        Map<String, String> params = new HashMap<>();
+        request.getParameterMap().forEach((name, values) -> {
+            String value = String.join(",", values);
+            params.put(name, value);
+        });
+        return params;
+    }
+
+    private static boolean verifyNotifyWithAlipaySdk(Map<String, String> params, AlipayNotifyConfig config) throws Exception {
+        return AlipaySignature.rsaCheckV1(
+            params,
+            config.alipayPublicKey(),
+            CHARSET,
+            params.getOrDefault("sign_type", "RSA2")
+        );
+    }
+
+    private static boolean businessFieldsMatch(MerchantOrder order, Map<String, String> params, AlipayNotifyConfig config) {
+        return config.appId().equals(params.get("app_id"))
+            && order.outTradeNo().equals(params.get("out_trade_no"))
+            && amountEquals(order.totalAmount(), params.get("total_amount"))
+            && expectedSellerMatches(config, params.get("seller_id"), params.get("seller_email"));
+    }
+
+    private static boolean amountEquals(BigDecimal expected, String actual) {
+        if (actual == null) return false;
+        try {
+            return expected.compareTo(new BigDecimal(actual)) == 0;
+        } catch (NumberFormatException e) {
+            return false;
+        }
+    }
+
+    private static boolean isPaidTradeNotification(Map<String, String> params) {
+        boolean paidStatus = "TRADE_SUCCESS".equals(params.get("trade_status")) || "TRADE_FINISHED".equals(params.get("trade_status"));
+        return paidStatus
+            && isBlank(params.get("out_biz_no"))
+            && isBlank(params.get("gmt_refund"))
+            && isBlank(params.get("refund_fee"));
+    }
+
+    private static boolean expectedSellerMatches(AlipayNotifyConfig config, String sellerId, String sellerEmail) {
+        String expectedSellerId = blankToNull(config.sellerId());
+        String expectedSellerEmail = blankToNull(config.sellerEmail());
+        return (expectedSellerId != null && expectedSellerId.equals(sellerId))
+            || (expectedSellerEmail != null && expectedSellerEmail.equals(sellerEmail));
+    }
+
+    private static boolean isBlank(String value) {
+        return value == null || value.isBlank();
+    }
+
+    private static String blankToNull(String value) {
+        return isBlank(value) ? null : value;
+    }
+
+    private String fail(String message, Map<String, String> params) {
+        safeLogNotifyError(message, params);
+        return "fail";
+    }
+
+    private void safeLogNotifyError(String message, Map<String, String> params) {
+        try {
+            notifyLogger.warn(message, sanitizeNotifyParams(params));
+        } catch (Exception ignored) {
+            // 日志失败不能影响支付宝收到纯文本 fail。
+        }
+    }
+
+    private static Map<String, String> sanitizeNotifyParams(Map<String, String> params) {
+        Map<String, String> safeParams = new HashMap<>(params);
+        safeParams.remove("sign");
+        return safeParams;
+    }
+
+    // 以下接口对接商家项目的真实配置、订单仓储、通知事件表和脱敏日志。
+    // 生产环境必须使用持久化订单表和通知事件表；内存 Map 只能用于非生产 demo。
+    private interface PaymentConfigRepository {
+        AlipayNotifyConfig findByAppId(String appId);
+    }
+
+    private interface OrderRepository {
+        MerchantOrder findByOutTradeNo(String outTradeNo);
+        void markPaidIdempotently(String outTradeNo, String tradeNo, Map<String, String> params);
+        void recordNonPaidTradeEvent(String outTradeNo, String tradeStatus, Map<String, String> params);
+    }
+
+    private interface NotifyEventRepository {
+        boolean insertOnce(String notifyId, String tradeNo, String outTradeNo, String tradeStatus, Map<String, String> params);
+    }
+
+    private interface NotifyLogger {
+        void warn(String message, Map<String, String> params);
+    }
+
+    private record AlipayNotifyConfig(String appId, String alipayPublicKey, String sellerId, String sellerEmail) {}
+    private record MerchantOrder(String outTradeNo, BigDecimal totalAmount) {}
+}
+```
+
+要点：
+
+- 支付宝通知是 POST 表单，验签前必须收集完整参数 map。
+- `AlipaySignature.rsaCheckV1` 会忽略 `sign` / `sign_type` 完成验签，业务代码不要先删除或改写参数。
+- `app_id`、`seller_id` / `seller_email` 从运行时支付配置校验，不从订单对象默认取值。
+- 金额校验使用 `BigDecimal` 或项目定点数工具，不要用浮点数直接比较。
+- 只有付款成功状态且不是退款、关单、分账等事件时，才认定付款成功。
+- 内存订单或内存幂等只能用于非生产 demo，生产必须使用持久化订单表和通知事件表。
+- 处理成功后返回纯文本 `success`；异常、验签失败或业务校验失败返回 `fail`。

package/skill/references/integration/modules/code-examples/java/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 @@ public class AlipayTradePagePay {
         AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
 
         AlipayTradePagePayRequest request = new AlipayTradePagePayRequest();
-        request.setNotifyUrl("https://your-domain.com/notify");  // 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+        String notifyUrl = System.getenv("ALIPAY_NOTIFY_URL");
+        if (notifyUrl != null && !notifyUrl.isBlank()) {
+            request.setNotifyUrl(notifyUrl.trim());  // 真实生产或公网联调时传入；本地没有公网 HTTPS notifyUrl 时不要调用 setNotifyUrl(null/空字符串/占位 URL)
+        }
         request.setReturnUrl("https://your-domain.com/return");  // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
         AlipayTradePagePayModel model = new AlipayTradePagePayModel();

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 示例
+
+适用产品：AI 网页应用收款、AI 移动应用收款。AI 按量付费不使用异步通知。
+
+```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 示例
+
+适用产品：AI 网页应用收款、AI 移动应用收款。AI 按量付费不使用异步通知。
+
+```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>' // 请填写您的应用私钥（用于商家签名）