@alipay/alipay-aipay 1.7.0 → 1.7.1

package/skill-pre/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-pre/references/integration/modules/code-examples/java/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,72 @@
+# 统一收单交易关闭接口 - Java 示例
+
+## 请求示例
+
+```java
+package com.java.sdk.demo;
+
+import com.alipay.api.AlipayApiException;
+import com.alipay.api.AlipayClient;
+import com.alipay.api.DefaultAlipayClient;
+import com.alipay.api.AlipayConfig;
+import com.alipay.api.domain.AlipayTradeCloseModel;
+import com.alipay.api.response.AlipayTradeCloseResponse;
+import com.alipay.api.request.AlipayTradeCloseRequest;
+
+public class AlipayTradeClose {
+
+    public static void main(String[] args) throws AlipayApiException {
+        // 初始化SDK（Java 使用 PKCS#8 格式私钥，C#/Python 使用 PKCS#1 格式，请勿混用）
+        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
+
+        AlipayTradeCloseRequest request = new AlipayTradeCloseRequest();
+        AlipayTradeCloseModel model = new AlipayTradeCloseModel();
+        model.setOutTradeNo("MERCHANT_ORDER_NO_PLACEHOLDER");  // 商户订单号，与 tradeNo 二选一
+        // model.setTradeNo("ALIPAY_TRADE_NO_PLACEHOLDER");  // 支付宝交易号，同时传时以 tradeNo 为准
+        request.setBizModel(model);
+
+        AlipayTradeCloseResponse response = alipayClient.execute(request);
+
+        if (response.isSuccess()) {
+            System.out.println("交易关闭成功");
+        } else {
+            System.out.println("调用失败: " + response.getSubCode() + " - " + response.getSubMsg());
+        }
+    }
+
+    private static AlipayConfig getAlipayConfig() {
+        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+        AlipayConfig alipayConfig = new AlipayConfig();
+        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
+        // 沙箱环境: alipayConfig.setServerUrl("https://openapi-sandbox.dl.alipaydev.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;
+    }
+}
+```
+
+## 响应示例
+### 正常示例
+```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/java/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,96 @@
+# 统一收单交易查询接口 - Java 示例
+
+## 请求示例
+
+```java
+package com.java.sdk.demo;
+
+import com.alipay.api.AlipayApiException;
+import com.alipay.api.AlipayClient;
+import com.alipay.api.DefaultAlipayClient;
+import com.alipay.api.AlipayConfig;
+import com.alipay.api.response.AlipayTradeQueryResponse;
+import com.alipay.api.request.AlipayTradeQueryRequest;
+import com.alipay.api.domain.AlipayTradeQueryModel;
+
+public class AlipayTradeQuery {
+
+    public static void main(String[] args) throws AlipayApiException {
+        // 初始化SDK（Java 使用 PKCS#8 格式私钥，C#/Python 使用 PKCS#1 格式，请勿混用）
+        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
+
+        AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
+        AlipayTradeQueryModel model = new AlipayTradeQueryModel();
+        model.setOutTradeNo("MERCHANT_ORDER_NO_PLACEHOLDER");  // 商户订单号，与 tradeNo 二选一
+        // model.setTradeNo("ALIPAY_TRADE_NO_PLACEHOLDER");  // 支付宝交易号，同时传时以 tradeNo 为准
+        request.setBizModel(model);
+
+        AlipayTradeQueryResponse response = alipayClient.execute(request);
+
+        if (response.isSuccess()) {
+            String businessState;
+            String tradeStatus = response.getTradeStatus();
+            switch (tradeStatus == null ? "" : tradeStatus) {
+                case "TRADE_SUCCESS":
+                case "TRADE_FINISHED":
+                    businessState = "PAID";
+                    break;
+                case "WAIT_BUYER_PAY":
+                    businessState = "PENDING_PAYMENT";
+                    break;
+                case "TRADE_CLOSED":
+                    businessState = "CLOSED";
+                    break;
+                default:
+                    businessState = "UNKNOWN";
+            }
+            System.out.println("业务状态: " + businessState + ", 支付宝状态: "
+                + tradeStatus + ", 订单金额: " + response.getTotalAmount());
+        } else {
+            System.out.println("调用失败: " + response.getSubCode() + " - " + response.getSubMsg());
+        }
+    }
+
+    private static AlipayConfig getAlipayConfig() {
+        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+        AlipayConfig alipayConfig = new AlipayConfig();
+        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
+        // 沙箱环境: alipayConfig.setServerUrl("https://openapi-sandbox.dl.alipaydev.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;
+    }
+}
+```
+
+## 响应示例
+### 正常示例
+```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/java/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,81 @@
+# 统一收单交易退款接口 - Java 示例
+
+## 请求示例
+
+```java
+package com.java.sdk.demo;
+
+import com.alipay.api.AlipayApiException;
+import com.alipay.api.AlipayClient;
+import com.alipay.api.DefaultAlipayClient;
+import com.alipay.api.AlipayConfig;
+import com.alipay.api.domain.AlipayTradeRefundModel;
+import com.alipay.api.request.AlipayTradeRefundRequest;
+import com.alipay.api.response.AlipayTradeRefundResponse;
+
+public class AlipayTradeRefund {
+
+    public static void main(String[] args) throws AlipayApiException {
+        // 初始化SDK（Java 使用 PKCS#8 格式私钥，C#/Python 使用 PKCS#1 格式，请勿混用）
+        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
+
+        AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();
+        AlipayTradeRefundModel model = new AlipayTradeRefundModel();
+        model.setOutTradeNo("MERCHANT_ORDER_NO_PLACEHOLDER");  // 商户订单号，与 tradeNo 二选一
+        model.setRefundAmount("200.12");            // 使用十进制定点金额；调用前校验累计退款不超过原订单实付金额
+        model.setRefundReason("正常退款");           // 退款原因，选填
+        model.setOutRequestNo("OUT_REQUEST_NO_PLACEHOLDER"); // 新退款使用新编号；同一退款失败重试必须复用原编号和原参数
+        request.setBizModel(model);
+
+        AlipayTradeRefundResponse response = alipayClient.execute(request);
+
+        if (response.isSuccess()) {
+            if ("Y".equals(response.getFundChange())) {
+                System.out.println("退款资金已发生变化，退款金额: " + response.getRefundFee());
+            } else {
+                System.out.println("退款结果待确认：使用同一 out_request_no 调用 alipay.trade.fastpay.refund.query");
+            }
+        } else {
+            System.out.println("调用失败: " + response.getSubCode() + " - " + response.getSubMsg());
+        }
+    }
+
+    private static AlipayConfig getAlipayConfig() {
+        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+        AlipayConfig alipayConfig = new AlipayConfig();
+        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
+        // 沙箱环境: alipayConfig.setServerUrl("https://openapi-sandbox.dl.alipaydev.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;
+    }
+}
+```
+
+## 响应示例
+### 正常示例
+```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": "88.88"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

package/skill-pre/references/integration/modules/code-examples/java/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,77 @@
+# 统一收单交易退款查询接口 - Java 示例
+
+## 请求示例
+
+```java
+package com.java.sdk.demo;
+
+import com.alipay.api.AlipayApiException;
+import com.alipay.api.AlipayClient;
+import com.alipay.api.DefaultAlipayClient;
+import com.alipay.api.AlipayConfig;
+import com.alipay.api.domain.AlipayTradeFastpayRefundQueryModel;
+import com.alipay.api.response.AlipayTradeFastpayRefundQueryResponse;
+import com.alipay.api.request.AlipayTradeFastpayRefundQueryRequest;
+
+public class AlipayTradeFastpayRefundQuery {
+
+    public static void main(String[] args) throws AlipayApiException {
+        // 初始化SDK（Java 使用 PKCS#8 格式私钥，C#/Python 使用 PKCS#1 格式，请勿混用）
+        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
+
+        AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest();
+        AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel();
+        model.setOutTradeNo("MERCHANT_ORDER_NO_PLACEHOLDER");  // 商户订单号，与 tradeNo 二选一
+        model.setOutRequestNo("OUT_REQUEST_NO_PLACEHOLDER");         // 退款请求号，必填，同一笔交易多次部分退款时用于区分
+        request.setBizModel(model);
+
+        AlipayTradeFastpayRefundQueryResponse response = alipayClient.execute(request);
+
+        if (response.isSuccess()) {
+            // refund_status: REFUND_SUCCESS 表示退款成功，REFUND_PROCESSING 表示退款处理中
+            System.out.println("退款状态: " + response.getRefundStatus() + ", 退款金额: " + response.getRefundAmount());
+        } else {
+            System.out.println("调用失败: " + response.getSubCode() + " - " + response.getSubMsg());
+        }
+    }
+
+    private static AlipayConfig getAlipayConfig() {
+        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+        AlipayConfig alipayConfig = new AlipayConfig();
+        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
+        // 沙箱环境: alipayConfig.setServerUrl("https://openapi-sandbox.dl.alipaydev.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;
+    }
+}
+```
+
+## 响应示例
+### 正常示例
+```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": "100.20",
+    "refund_amount": "12.33",
+    "refund_status": "REFUND_SUCCESS"
+}
+```
+### 异常示例
+```json
+{
+    "code": "20000",
+    "msg": "Service Currently Unavailable",
+    "sub_code": "isp.unknow-error",
+    "sub_msg": "系统繁忙"
+}
+```

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

@@ -0,0 +1,69 @@
+# 统一收单下单并支付页面接口 - Java 示例
+
+## 请求示例
+
+```java
+package com.java.sdk.demo;
+
+import com.alipay.api.AlipayApiException;
+import com.alipay.api.AlipayClient;
+import com.alipay.api.DefaultAlipayClient;
+import com.alipay.api.AlipayConfig;
+import com.alipay.api.domain.AlipayTradePagePayModel;
+import com.alipay.api.response.AlipayTradePagePayResponse;
+import com.alipay.api.request.AlipayTradePagePayRequest;
+
+public class AlipayTradePagePay {
+
+    public static void main(String[] args) throws AlipayApiException {
+        // 初始化SDK（Java 使用 PKCS#8 格式私钥，C#/Python 使用 PKCS#1 格式，请勿混用）
+        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());
+
+        AlipayTradePagePayRequest request = new AlipayTradePagePayRequest();
+        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();
+        model.setOutTradeNo("MERCHANT_ORDER_NO_PLACEHOLDER");             // 商户订单号，必填
+        model.setTotalAmount("88.88");                        // 订单总金额，必填，单位为元
+        model.setSubject("Iphone6 16G");                      // 订单标题，必填
+        model.setProductCode("FAST_INSTANT_TRADE_PAY");       // 网站支付固定值，必填
+        request.setBizModel(model);
+
+        // ⚠️ 网站支付必须使用 pageExecute()，不能使用 execute()
+        // ⚠️ 必须使用 POST 模式：alipayClient.pageExecute(request, "POST")
+        AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "POST");
+        String formHtml = response.getBody();
+        // pageExecute 返回的是 HTML 表单字符串，前端需要渲染并自动提交
+        System.out.println(formHtml);
+    }
+
+    private static AlipayConfig getAlipayConfig() {
+        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIE...（脱敏示例） -->";
+        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIB...（脱敏示例） -->";
+        AlipayConfig alipayConfig = new AlipayConfig();
+        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
+        // 沙箱环境: alipayConfig.setServerUrl("https://openapi-sandbox.dl.alipaydev.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;
+    }
+}
+```
+
+## 响应示例
+### 正常示例
+```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;88.88&quot;,&quot;subject&quot;:&quot;Iphone6 16G&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>
+```