编辑 | blame | 历史 | 原始文档

支付宝第三方接口使用说明

概述

本模块新增了支付宝当面付第三方接口，用于调用旧系统的支付宝支付接口生成支付URL和二维码。

功能说明

接口地址

Controller接口: POST /api/pay/alipay/thirdparty/precreate
第三方接口: https://sys.966120.com.cn/alipay_pay_QR_NotifyUrl.php

实现流程

接收前端支付请求
创建或查询订单记录
调用第三方支付宝接口生成支付URL
将支付URL生成二维码（Base64格式）
创建交易记录
返回支付信息给前端

请求参数

请求示例

{
  "bizOrderId": "BF20250012-1",
  "amount": 10000,
  "subject": "急救转运服务费",
  "description": "急救转运任务支付",
  "callbackUrl": "https://dsp.966120.com.cn/alipay/pay_notify"
}

参数说明

参数名	类型	必填	说明
bizOrderId	String	是	业务订单号（如：BF20250012-1）
amount	Integer	是	订单金额，单位：分（如：10000表示100.00元）
subject	String	是	订单标题
description	String	否	订单描述
callbackUrl	String	是	支付成功后的回调通知地址

响应参数

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "orderId": 1234567890123456789,
    "transactionId": 9876543210987654321,
    "status": "PENDING",
    "qrBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expireAt": "2025-11-24T18:00:00"
  }
}

响应参数说明

参数名	类型	说明
orderId	Long	支付订单ID
transactionId	Long	交易流水ID
status	String	订单状态（PENDING-待支付）
qrBase64	String	二维码图片Base64编码
expireAt	DateTime	订单过期时间（2小时后）

调用第三方接口参数映射

调用第三方接口时，参数映射关系如下：

第三方参数	来源	说明
notify_url	callbackUrl	异步回调通知地址
out_trade_no	orderId	支付模块生成的订单ID
total_fee	amount	订单金额（分）
ServiceOrdID	bizOrderId	业务订单号

curl示例

curl --location --request POST 'https://sys.966120.com.cn/alipay_pay_QR_NotifyUrl.php' \
--header 'Cookie: CAMEName=' \
--form 'notify_url="https://dsp.966120.com.cn/alipay/pay_notify"' \
--form 'out_trade_no="1234567890123456789"' \
--form 'total_fee="10000"' \
--form 'ServiceOrdID="BF20250012-1"'

代码实现

核心类说明

1. AlipayThirdPartyClient

位置: com.ruoyi.payment.infrastructure.channel.alipay.AlipayThirdPartyClient
功能: 封装第三方支付宝接口调用逻辑
主要方法:
createQrCodeUrl(): 调用第三方接口生成支付URL

2. PaymentService

位置: com.ruoyi.payment.application.service.PaymentService
功能: 支付业务逻辑处理
主要方法:
createAlipayThirdPartyPrecreate(): 发起第三方支付宝当面付

3. PaymentController

位置: com.ruoyi.payment.interfaces.controller.PaymentController
功能: 提供HTTP接口
接口路径: POST /api/pay/alipay/thirdparty/precreate

使用示例

前端调用示例

// 发起支付
async function createPayment() {
  const response = await fetch('/api/pay/alipay/thirdparty/precreate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      bizOrderId: 'BF20250012-1',
      amount: 10000,
      subject: '急救转运服务费',
      description: '急救转运任务支付',
      callbackUrl: 'https://dsp.966120.com.cn/alipay/pay_notify'
    })
  });
  
  const result = await response.json();
  
  if (result.code === 200) {
    // 显示二维码
    const qrImage = document.getElementById('qrImage');
    qrImage.src = result.data.qrBase64;
  }
}

注意事项

金额单位: 所有金额参数单位均为分，前端需要将元转换为分（乘以100）
订单过期: 订单默认2小时后过期，需在有效期内完成支付
重复调用: 同一业务订单号多次调用会返回已存在的支付记录，不会重复创建
回调地址: 必须配置正确的回调地址，用于接收支付成功通知
第三方接口响应格式: 需要根据实际返回格式调整 parseQrCodeUrl() 方法

与标准支付宝当面付接口的区别

特性	标准接口	第三方接口
接口地址	支付宝官方API	旧系统PHP接口
调用方式	支付宝SDK	HTTP POST multipart/form-data
返回内容	支付宝qr_code	支付URL
优势	官方支持、稳定	兼容旧系统、快速集成

配置说明

默认回调地址

如果请求中未指定callbackUrl，系统会使用默认回调地址：
https://dsp.966120.com.cn/alipay/pay_notify

可在 PaymentService.callAlipayThirdPartyPrecreate() 方法中修改默认值。

错误处理

常见错误码

错误码	说明	处理方式
500	第三方接口调用失败	检查网络连接和第三方接口可用性
500	未返回有效的支付URL	检查第三方接口返回格式
400	参数校验失败	检查请求参数是否完整

测试建议

先使用Postman或curl测试第三方接口可用性
验证第三方接口返回的URL格式
测试小额支付（如1元）验证完整流程
测试订单重复创建场景
测试订单过期场景

后续优化建议

响应解析: 根据第三方接口实际返回格式，完善 parseQrCodeUrl() 方法
错误重试: 增加第三方接口调用失败的重试机制
超时控制: 设置HTTP请求超时时间
日志完善: 增加更详细的调用日志，便于问题排查
监控告警: 对接口调用失败进行监控和告警