java支付宝接口教程
本文档为Java开发者提供全面、系统、可落地的支付宝开放平台接入指南,涵盖从环境准备、SDK集成、支付发起、异步通知处理、退款、转账到生产环境部署的全流程实践。内容基于支付宝开放平台最新文档(2024年11月更新),结合真实项目经验编写,强调可操作性与安全性,避免“纸上谈兵”式讲解。
在移动支付高度普及的今天,支付宝作为中国最大的第三方支付平台,其开放能力已成为企业数字化转型的关键基础设施。对于Java后端开发者而言,掌握支付宝接口集成不仅是技术能力的体现,更是产品商业化落地的必经之路。本教程将帮助您系统构建支付能力体系,从沙箱测试到生产上线,全程实战驱动。
为何选择本教程?
• java支付宝接口教程 采用“问题导向”结构,直击开发者高频痛点
• 所有示例代码均经沙箱环境验证,可直接复制运行
• 重点解析异步通知幂等性、签名验签、异常重试等易错环节
• 包含小程序支付、生活号支付、APP支付等多场景扩展方案
• 提供完整的日志追踪与监控建议,便于生产环境排查问题
本教程默认您已具备Java基础(Spring Boot框架优先)、HTTP协议基础及基本的API集成经验。我们将从“最小可用集成” 出发,逐步扩展至企业级支付系统架构,确保每个环节都有据可依、有码可验。
⚠️ 支付宝接口调用必须严格遵循安全规范 :所有请求参数需加密签名,敏感信息(如私钥)严禁硬编码在客户端,生产环境务必启用HTTPS。
基础环境与配置
1. 开发前准备
在开始编码前,请完成以下基础配置:
① 注册支付宝开放平台账号(https://open.alipay.com)
② 创建应用(企业/个体工商户资质),获取APPID 、支付宝网关 、公钥路径
③ 生成密钥对:使用支付宝提供的RSA2密钥生成工具(Java推荐使用OpenSSL)
④ 在应用配置中上传应用公钥 ,平台返回支付宝公钥
⑤ 启用沙箱环境(测试阶段强烈推荐)
沙箱环境是支付宝提供的模拟支付环境,所有资金操作均为虚拟交易,用于前期功能验证。沙箱账号包含:
沙箱账号 (买家)、沙箱卖家账号 、沙箱网关地址 、沙箱密钥 。请勿将沙箱参数混入生产环境。
# 沙箱环境关键参数示例(生产环境需替换为正式值)
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),流程如下:
将请求参数按key升序排列(忽略空值、sign、sign_type)
拼接成key1=value1&key2=value2...字符串
在末尾添加&sign_type=RSA2
使用应用私钥对字符串进行SHA256WithRSA签名
将签名结果Base64编码,作为sign参数
SDK已自动处理上述流程,开发者只需确保AlipayConfig中密钥正确即可。但需注意:签名参数必须包含在请求体中,不可仅靠URL参数 。
🔒 安全红线:切勿将私钥硬编码在前端代码或客户端代码中!所有签名操作必须在服务端完成。
支付流程实战:以网页扫码支付为例
支付宝网页支付(Alipay Trade Page Pay)是最常见的PC/移动端H5支付场景,用户扫描二维码或点击链接后跳转至支付宝完成支付。本节将完整演示从订单创建到页面跳转的实现逻辑。
1. 订单创建接口设计
创建订单时需包含以下核心字段:
out_trade_no:商户订单号(唯一性由业务系统保证)
total_amount:订单金额(单位:元,保留2位小数)
subject:订单标题(必填,长度≤128字符)
product_code:产品码,默认QUICK_WAP_WAY
time_expire:订单绝对超时时间(格式:yyyy-MM-dd HH:mm:ss)
goods_detail:商品明细(可选,用于分账场景)
@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支付
网页支付
手机网站支付
小程序支付
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);
}
关键参数说明:
out_request_no:退款请求号,同一订单的退款需保证唯一(建议:订单号+序列号)
refund_amount:本次退款金额,支持小数点后2位
refund_reason:退款原因(可选,≤128字符)
⚠️ 退款失败处理:若支付宝返回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. 账号类型说明
ALIPAY_LOGONID:支付宝登录名(邮箱/手机号),需用户授权
ALIPAY_USERID:支付宝2088账号,无需授权(推荐)
💡 最佳实践:在用户首次绑定银行卡时,同步获取其支付宝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. 签名与验签规范
支付宝所有接口调用必须签名,异步通知必须验签。常见错误:
签名参数遗漏空值参数(需过滤空值)
参数排序未按ASCII升序
使用错误的公钥(混淆应用公钥与支付宝公钥)
// 手动验签示例(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. 敏感信息处理
私钥存储:使用环境变量或加密配置中心(如Apollo、Nacos加密配置)
日志脱敏:禁止记录订单金额、银行卡号、身份证号等敏感信息
HTTPS强制启用:所有支付相关接口必须通过HTTPS传输
✅ 实战经验:在日志中记录订单号时,使用掩码处理: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);