欢迎访问 java支付宝接口教程 —— Java开发者专属支付集成指南

java支付宝接口教程

java支付宝接口教程

本文档为Java开发者提供全面、系统、可落地的支付宝开放平台接入指南,涵盖从环境准备、SDK集成、支付发起、异步通知处理、退款、转账到生产环境部署的全流程实践。内容基于支付宝开放平台最新文档(2024年11月更新),结合真实项目经验编写,强调可操作性与安全性,避免“纸上谈兵”式讲解。

在移动支付高度普及的今天,支付宝作为中国最大的第三方支付平台,其开放能力已成为企业数字化转型的关键基础设施。对于Java后端开发者而言,掌握支付宝接口集成不仅是技术能力的体现,更是产品商业化落地的必经之路。本教程将帮助您系统构建支付能力体系,从沙箱测试到生产上线,全程实战驱动。

为何选择本教程?

  • • java支付宝接口教程采用“问题导向”结构,直击开发者高频痛点
  • • 所有示例代码均经沙箱环境验证,可直接复制运行
  • • 重点解析异步通知幂等性、签名验签、异常重试等易错环节
  • • 包含小程序支付、生活号支付、APP支付等多场景扩展方案
  • • 提供完整的日志追踪与监控建议,便于生产环境排查问题

本教程默认您已具备Java基础(Spring Boot框架优先)、HTTP协议基础及基本的API集成经验。我们将从“最小可用集成”出发,逐步扩展至企业级支付系统架构,确保每个环节都有据可依、有码可验。

⚠️ 支付宝接口调用必须严格遵循安全规范:所有请求参数需加密签名,敏感信息(如私钥)严禁硬编码在客户端,生产环境务必启用HTTPS。

基础环境与配置

1. 开发前准备

在开始编码前,请完成以下基础配置:

沙箱环境是支付宝提供的模拟支付环境,所有资金操作均为虚拟交易,用于前期功能验证。沙箱账号包含:
沙箱账号(买家)、沙箱卖家账号、沙箱网关地址、沙箱密钥。请勿将沙箱参数混入生产环境。

# 沙箱环境关键参数示例(生产环境需替换为正式值) ALIPAY_APP_ID=2021000123456789 ALIPAY_GATEWAY=https://openapi.alipaydev.com/gateway.do ALIPAY_APP_PRIVATE_KEY=MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7... ALIPAY_ALIPAY_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA... ALIPAY_SIGN_TYPE=RSA2 ALIPAY_CHARSET=utf-8 ALIPAY_NOTIFY_URL=https://www.xservx.com/alipay/notify ALIPAY_RETURN_URL=https://www.xservx.com/alipay/return

2. 项目依赖配置

推荐使用Maven管理依赖,最新版SDK请参考官方GitHub:https://github.com/alipay/alipay-sdk-java

<dependency> <groupId>com.alipay.sdk</groupId> <artifactId>alipay-sdk-java</artifactId> <version>4.38.112.ALL</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>

版本说明:2023年后SDK统一使用4.x系列,废弃旧版3.x的AlipayClient构造方式。新SDK采用AlipayClient与AlipayConfig分离设计,更符合Spring Boot依赖注入规范。

⚡ 实战提示:在application.yml中集中管理配置参数,避免散落在多处;私钥建议使用Base64编码存储,运行时解码,防止明文泄露。

3. 初始化客户端

创建配置类,注入核心参数:

@Configuration public class AlipayConfig { @Value("${alipay.app-id}") private String appId; @Value("${alipay.app-private-key}") private String privateKey; @Value("${alipay.alipay-public-key}") private String alipayPublicKey; @Value("${alipay.gateway-url}") private String gatewayUrl; @Value("${alipay.sign-type}") private String signType = "RSA2"; @Value("${alipay.charset}") private String charset = "UTF-8"; @Bean public AlipayClient alipayClient() { AlipayConfig config = new AlipayConfig(); config.setAppId(appId); config.setPrivateKey(privateKey); config.setAlipayPublicKey(alipayPublicKey); config.setGatewayUrl(gatewayUrl); config.setSignType(signType); config.setCharset(charset); // 生产环境建议开启HTTPS config.setProtocol("https"); config.setPostCharset(charset); config.setFormat("json"); return new DefaultAlipayClient(config); } }

该配置类生成AlipayClient Bean,后续所有API调用均依赖此客户端实例。注意:私钥必须为PKCS8格式,若生成的是PKCS1格式,需转换:

# PKCS1 → PKCS8 转换(OpenSSL) openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt \ -in alipay_private_key_pkcs1.pem -out alipay_private_key_pkcs8.pem

4. 签名机制详解

支付宝采用RSA2签名算法(SHA256WithRSA),流程如下:

  1. 将请求参数按key升序排列(忽略空值、sign、sign_type)
  2. 拼接成key1=value1&key2=value2...字符串
  3. 在末尾添加&sign_type=RSA2
  4. 使用应用私钥对字符串进行SHA256WithRSA签名
  5. 将签名结果Base64编码,作为sign参数

SDK已自动处理上述流程,开发者只需确保AlipayConfig中密钥正确即可。但需注意:签名参数必须包含在请求体中,不可仅靠URL参数。

🔒 安全红线:切勿将私钥硬编码在前端代码或客户端代码中!所有签名操作必须在服务端完成。

支付流程实战:以网页扫码支付为例

支付宝网页支付(Alipay Trade Page Pay)是最常见的PC/移动端H5支付场景,用户扫描二维码或点击链接后跳转至支付宝完成支付。本节将完整演示从订单创建到页面跳转的实现逻辑。

1. 订单创建接口设计

创建订单时需包含以下核心字段:

@RestController @RequestMapping("/api/order") public class OrderController { @Autowired private AlipayClient alipayClient; @PostMapping("/create") public ResponseEntity> createOrder(@RequestBody OrderRequest request) { // 1. 构建订单基础参数 AlipayTradePagePayRequest alipayRequest = new AlipayTradePagePayRequest(); alipayRequest.setReturnUrl("/alipay/return"); alipayRequest.setNotifyUrl("/alipay/notify"); // 2. 构建业务参数(关键!) Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", request.getOutTradeNo()); bizContent.put("total_amount", new BigDecimal(request.getAmount()).setScale(2, RoundingMode.HALF_UP).toString()); bizContent.put("subject", request.getSubject()); bizContent.put("product_code", "FAST_INSTANT_TRADE_PAY"); bizContent.put("time_expire", LocalDateTime.now().plusMinutes(30).format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))); // 可选:设置商品明细 if (CollectionUtils.isNotEmpty(request.getGoodsList())) { List> goodsDetail = new ArrayList<>(); request.getGoodsList().forEach(goods -> { Map detail = new HashMap<>(); detail.put("goods_id", goods.getGoodsId()); detail.put("goods_name", goods.getGoodsName()); detail.put("quantity", goods.getQuantity()); detail.put("price", new BigDecimal(goods.getPrice()).setScale(2).toString()); goodsDetail.add(detail); }); bizContent.put("goods_detail", goodsDetail); } alipayRequest.setBizContent(JSON.toJSONString(bizContent)); // 3. 调用SDK生成支付页面URL String form = ""; try { form = alipayClient.pageExecute(alipayRequest).getBody(); } catch (AlipayApiException e) { log.error("订单创建失败", e); return ResponseEntity.badRequest().body(Map.of("error", "支付初始化失败")); } // 4. 返回HTML表单(浏览器自动提交) Map result = new HashMap<>(); result.put("html", form); return ResponseEntity.ok(result); } }

2. 支付回调处理

支付宝通过异步通知(notify_url)告知支付结果,同步跳转(return_url)仅用于展示。开发者必须以异步通知为准更新订单状态。

@RestController @RequestMapping("/alipay") public class AlipayCallbackController { @Autowired private AlipayClient alipayClient; @Autowired private OrderService orderService; // 同步跳转(展示支付结果页) @GetMapping("/return") public ModelAndView returnPage(@RequestParam Map params) { // 验签(可选,因同步参数易被篡改) boolean signVerified = AlipaySignature.rsaCheckV1(params, alipayClient.getAlipayPublicKey(), "UTF-8", "RSA2"); ModelAndView mv = new ModelAndView("alipay/return"); mv.addObject("result", signVerified ? "success" : "failed"); return mv; } // 异步通知(核心!必须验签+幂等处理) @PostMapping("/notify") public String notify(@RequestBody Map params) { try { // 1. 验签(防止伪造通知) boolean signVerified = AlipaySignature.rsaCheckV1(params, alipayClient.getAlipayPublicKey(), "UTF-8", "RSA2"); if (!signVerified) { log.warn("异步通知验签失败:{}", params); return "fail"; } // 2. 提取关键字段 String outTradeNo = params.get("out_trade_no"); String tradeNo = params.get("trade_no"); String tradeStatus = params.get("trade_status"); String gmtPayment = params.get("gmt_payment"); // 3. 更新订单状态(幂等处理) if ("TRADE_SUCCESS".equals(tradeStatus) || "TRADE_FINISHED".equals(tradeStatus)) { orderService.updateOrderStatus(outTradeNo, tradeNo, tradeStatus, gmtPayment); } return "success"; } catch (Exception e) { log.error("异步通知处理异常", e); return "fail"; } } }
⚙️ 幂等性保障:订单状态更新时需判断当前状态,避免重复处理;建议使用UPDATE ... WHERE status='UNPAID' + 检查影响行数实现。

3. 订单查询与关单

支付成功后,可通过alipay.trade.query查询订单状态,适用于用户刷新页面未触发异步通知的场景:

public AlipayTradeQueryResponse queryOrder(String outTradeNo) { AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", outTradeNo); request.setBizContent(JSON.toJSONString(bizContent)); return alipayClient.execute(request); }

若订单超时未支付,可调用alipay.trade.close主动关闭订单:

public AlipayTradeCloseResponse closeOrder(String outTradeNo) { AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", outTradeNo); request.setBizContent(JSON.toJSONString(bizContent)); return alipayClient.execute(request); }

4. 前端集成示例

支付结果页(HTML)需接收后端返回的html字段并渲染:

<div id="alipay-form" style="display:none;"></div> <script> fetch('/api/order/create', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({outTradeNo: 'ORD20241101001', amount: 0.01, subject: '测试订单'}) }) .then(res => res.json()) .then(data => { document.getElementById('alipay-form').innerHTML = data.html; document.getElementById('alipay-form').style.display = 'block'; // 表单会自动提交 }); </script>

核心交易API深度解析

APP支付(Alipay Trade App Pay)

适用于Android/iOS原生APP,流程为:后端生成订单 → 调用SDK生成订单字符串 → 前端调用支付宝APP唤起支付 → 支付成功后回调。

// 后端生成订单字符串(关键!) public String createAppOrder(OrderRequest request) { AlipayTradeAppPayRequest request = new AlipayTradeAppPayRequest(); request.setNotifyUrl("/alipay/notify"); Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", request.getOutTradeNo()); bizContent.put("total_amount", request.getAmount()); bizContent.put("subject", request.getSubject()); bizContent.put("product_code", "QUICK_MSECURITY_PAY"); request.setBizContent(JSON.toJSONString(bizContent)); // 返回订单字符串(非HTML) AlipayTradeAppPayResponse response = alipayClient.sdkExecute(request); return response.getBody(); }

前端(Android/iOS)使用该字符串调用支付宝SDK的payV2方法。注意:订单字符串必须直接传递,不可二次签名。

⚠️ 注意:2023年后支付宝停止更新APP支付SDK,新项目建议使用统一收单交易接口 + H5支付页替代。

网页支付(Alipay Trade Page Pay)

适用于PC端网站,用户在支付宝页面完成支付。与上述示例一致,重点在于:必须设置return_url和notify_url。

🔍 技术细节:支付宝会将订单参数Base64编码后放入HTML表单的hidden字段,浏览器自动提交表单跳转。

手机网站支付(Alipay Trade Wap Pay)

专为移动端H5设计,支持微信内打开、浏览器直接访问。需设置quit_url(用户中途退出支付的跳转页)。

// WAP支付配置示例 AlipayTradeWapPayRequest request = new AlipayTradeWapPayRequest(); request.setReturnUrl("/pay/return"); request.setNotifyUrl("/pay/notify"); request.setQuitUrl("/pay/quit"); // 用户点击“返回商家”跳转页 Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", "WAP20241101001"); bizContent.put("total_amount", "0.01"); bizContent.put("subject", "手机网站支付测试"); bizContent.put("product_code", "QUICK_WAP_WAY"); request.setBizContent(JSON.toJSONString(bizContent));

用户支付后,支付宝会跳转至return_url,但最终订单状态仍以异步通知为准。

小程序支付(Alipay Trade Mini Program Pay)

适用于支付宝小程序内的商品购买,流程为:小程序前端调用my.tradePay → 传入后端生成的trade_no(预下单返回)→ 支付成功后回调。

// 后端预下单(返回trade_no) public String prepay(String outTradeNo, String amount, String subject) { AlipayTradePrecreateRequest request = new AlipayTradePrecreateRequest(); request.setNotifyUrl("/alipay/notify"); Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", outTradeNo); bizContent.put("total_amount", amount); bizContent.put("subject", subject); request.setBizContent(JSON.toJSONString(bizContent)); AlipayTradePrecreateResponse response = alipayClient.execute(request); return response.getTradeNo(); // 返回支付宝交易号 }

小程序端调用示例:

my.tradePay({ tradeNO: '20241101000012345678901234', // 支付宝交易号 success: (res) => { // 支付成功(需二次验证) if (res.resultCode === '9000') { // 调用后端查询接口确认状态 } } });

退款与资金安全

1. 单笔退款(Alipay Trade Refund)

退款是支付闭环的关键环节,支持部分退款与全额退款。注意:退款金额不得超过原支付金额,且需在订单有效期内操作。

public AlipayTradeRefundResponse refund(String outTradeNo, String outRequestNo, String refundAmount) { AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", outTradeNo); bizContent.put("out_request_no", outRequestNo); // 退款请求号(同一订单可多次退款) bizContent.put("refund_amount", refundAmount); // 退款金额(字符串格式) request.setBizContent(JSON.toJSONString(bizContent)); return alipayClient.execute(request); }

关键参数说明:

⚠️ 退款失败处理:若支付宝返回code=ACQ.TRADE_NOT_EXIST,说明订单不存在;ACQ.TRADE_NOT_ALLOW_REFUND表示订单状态不允许退款(如已关闭)。

2. 退款查询(Alipay Trade Fastpay Refund Query)

用于确认退款是否成功,避免因网络问题导致状态不一致:

public AlipayTradeFastpayRefundQueryResponse queryRefund(String outTradeNo, String outRequestNo) { AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); Map bizContent = new HashMap<>(); bizContent.put("out_trade_no", outTradeNo); bizContent.put("out_request_no", outRequestNo); request.setBizContent(JSON.toJSONString(bizContent)); return alipayClient.execute(request); }

3. 退款通知(异步)

支付宝会通过notify_url推送退款结果,需单独处理:

@PostMapping("/alipay/refund/notify") public String refundNotify(@RequestBody Map params) { // 验签(同支付通知) boolean signVerified = AlipaySignature.rsaCheckV1(params, ...); if (!signVerified) return "fail"; String outTradeNo = params.get("out_trade_no"); String outRequestNo = params.get("out_request_no"); String refundAmount = params.get("refund_amount"); String gmtRefundPay = params.get("gmt_refund_pay"); // 更新退款状态 orderService.updateRefundStatus(outTradeNo, outRequestNo, refundAmount, gmtRefundPay); return "success"; }

转账到支付宝账户(企业付款)

除收款外,企业常需向用户转账(如退款至余额、佣金结算)。支付宝提供单笔转账到支付宝账户接口(alipay.fund.trans.uni.transfer)。

public AlipayFundTransUniTransferResponse transfer(String outBizNo, String transAmount, String payeeType, String payeeAccount) { AlipayFundTransUniTransferRequest request = new AlipayFundTransUniTransferRequest(); Map bizContent = new HashMap<>(); bizContent.put("out_biz_no", outBizNo); // 商户转账订单号(唯一) bizContent.put("trans_amount", transAmount); // 转账金额(字符串,单位:元) bizContent.put("product_code", "TRANS_ACCOUNT_NO_PWD"); // 无密转账 bizContent.put("biz_scene", "DIRECT_TRANSFER"); // 场景码 bizContent.put("payee_info", JSON.toJSONString(Map.of( "type", payeeType, // ALIPAY_LOGONID(登录名)或 ALIPAY_USERID(2088开头) "identity", payeeAccount ))); request.setBizContent(JSON.toJSONString(bizContent)); return alipayClient.execute(request); }

1. 账号类型说明

💡 最佳实践:在用户首次绑定银行卡时,同步获取其支付宝2088账号并存储,后续转账直接使用。

2. 转账查询(alipay.fund.trans.common.query)

用于确认转账结果,避免重复发起:

public AlipayFundTransCommonQueryResponse queryTransfer(String outBizNo) { AlipayFundTransCommonQueryRequest request = new AlipayFundTransCommonQueryRequest(); Map bizContent = new HashMap<>(); bizContent.put("out_biz_no", outBizNo); request.setBizContent(JSON.toJSONString(bizContent)); return alipayClient.execute(request); }
⚠️ 注意:单日转账限额受支付宝规则限制(如:未认证用户≤5000元/日),企业账户需开通“单笔转账到支付宝账户”权限。

安全与风控要点

1. 签名与验签规范

支付宝所有接口调用必须签名,异步通知必须验签。常见错误:

// 手动验签示例(SDK已封装,仅作原理说明) public boolean manualVerify(Map params, String publicKey) { // 1. 提取sign与sign_type String sign = params.remove("sign"); params.remove("sign_type"); // 2. 排序拼接 List keys = new ArrayList<>(params.keySet()); Collections.sort(keys); StringBuilder sb = new StringBuilder(); for (String key : keys) { if (StringUtils.isNotBlank(params.get(key))) { sb.append(key).append("=").append(params.get(key)).append("&"); } } String content = sb.deleteCharAt(sb.length()-1).toString(); // 3. 验签 return AlipaySignature.rsaVerify(content, sign, publicKey, "UTF-8", "RSA2"); }

2. 敏感信息处理

✅ 实战经验:在日志中记录订单号时,使用掩码处理:ORD202411***001

3. 防重放攻击

支付宝通过timestamp参数防止重放攻击,要求请求时间与支付宝服务器时间差≤15分钟。建议:

// 生成时间戳(Java) String timestamp = LocalDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));

高频问题与解决方案

Q1:为什么异步通知收不到?

可能原因:

  • • 网络问题:检查服务器防火墙是否放行支付宝IP段(https://opendocs.alipay.com/common/02kh2v)
  • • URL错误:确保notify_url为公网可访问地址(沙箱需用测试域名)
  • • 请求体解析错误:Spring Boot需使用@RequestBody Map接收(不可用String)
  • • 验签失败导致逻辑中断:检查日志中验签结果
🔍 排查步骤:1. 用Postman模拟异步通知;2. 查看支付宝开放平台“消息中心”日志;3. 检查服务器访问日志。

Q2:订单金额精度问题

支付宝要求金额为字符串类型,且保留2位小数。错误示例:0.1应为"0.10"。使用BigDecimal处理:

String amount = new BigDecimal("0.1").setScale(2, RoundingMode.HALF_UP).toString(); // "0.10"

若传入0.1,支付宝会返回ACQ.INVALID_PARAMETER错误。

Q3:沙箱环境支付成功但异步通知失败?

沙箱环境通知可能存在延迟(通常≤30秒),建议在沙箱测试时:
① 使用支付宝提供的“模拟异步通知”工具(https://openhome.alipay.com/platform/appDaily.htm);
② 在异步通知接口中添加日志,确认是否收到请求。

Q4:如何实现分账?

分账需满足:
① 商户已开通“分账”功能;
② 支付时传入royalty_parameters参数;
③ 分账结果通过异步通知或主动查询获取。

// 分账参数示例 Map royalty = new HashMap<>(); List> details = new ArrayList<>(); details.add(Map.of( "trans_in", "2088102123456789", "trans_out", "2088102198765432", "amount", "0.01", "desc", "服务费" )); royalty.put("royalty_type", "division"); royalty.put("royalty_parameters", details);