统一退款接口

提示

当交易发生之后一段时间内，可以通过统一退款接口将支付款退还给买家，支持多次退款，超过约定时间的订单无法进行退款。除了使用接口API方式对订单退款， 也可以在管理后台使用界面进行手工操作。

退款请求可以重复提交，多次请求会保持退款的幂等性，不会触发重复退款。但重复提交时只有 商户扩展参数、异步通知地址 、用户IP 、签名值 、请求时间字段可以传输不同的值， 其他参数需要与首次下单的数值一致，传输不同的值也不会生效。

接口说明

参数	说明
请求URL	/unipay/refund
请求方式	POST
请求类型	application/json

请求参数

公共参数

字段名	变量名	必填	类型	长度	示例值	描述
应用号	appId	否	String	32	A112544225541	此次操作所要使用的支付应用号
用户IP	clientIp	否	String	64	127.0.0.1	支持V4和V6，部分支付方式要求必填，如调用微信支付方式时
随机数值	nonceStr	否	String	32	d112892e382a7093
签名值	sign	否	String	64	072695d112892e382a7093b81e6a52af
请求时间	reqTime	是	String		2024-10-24 12:00:00	请求时间和当前时间误差不要超过五分钟，时间格式 yyyy-MM-dd HH:mm:ss

业务参数

字段名	变量名	必填	类型	长度	描述	示例值
商户退款号	bizRefundNo	是	String	100	同样的商户退款号多次请求，同一退款单号多次请求只退一笔	R10893
支付订单号	orderNo	否	String	32	与商户订单号至少要传输一个，同时传输以订单号为准	1753370980523384832
商户支付订单号	bizOrderNo	否	String	100	与订单号至少要传输一个，同时传输以订单号为准	P0001
退款金额	amount	是	BigDecimal	8,2	10.12	要进行退款的金额，,单位为元，保留两位小数
退款原因	reason	否	String	150	进行退款的原因，非必填	测试退款
预留的退款扩展参数	extraParam	否	ChannelParam	2048	暂时未使用
商户扩展参数	attach	否	String	500	商户扩展参数，回调时会原样返回	id=123332
异步通知地址	notifyUrl	否	String	200	异步通知地址	http://abc.cn/noticeCallback

响应结果

通用响应参数

WARNING

状态码返回0只代表受理业务成功，业务是否成功需要看具体业务的返回信息，不为0表示受理失败，具体响应吗可以参考返回状态码

名称	字段	类型	示例值	描述
状态码	code	Integer	0	默认是0，非0表明请求失败，例如签名错误等
提示信息	msg	String		发生错误时会有数据返回
业务数据	data	Json字符串		json格式数据，不同的接口返回结构不同，可以参考业务公共响应参数
签名	sign	String	sIV4zJVhZ4Uz	返回数据的签名值
响应时间	resTime	String	2024-08-08 12:12:12	数据响应的时间, 如果时间与请求时间相差5分钟以上，请排查网络和安全问题
追踪ID	traceId	String	sIV4zJVhZ4Uz	用于查询日志排查问题时进行快速定位

业务响应参数

提示

业务数据包裹在公共响应参数中的data字段，在code为0时才会有返回数据。

字段名	变量名	必传	类型	示例值	描述
退款号	refundNo	是	String	DEVR24051019590563000001	系统生成的退款单号
商户退款号	bizRefundNo	是	String	R00123	商户退款时传入的退款单号
退款状态	status	是	String	success	见退款状态说明
错误提示	errorMsg	否	String	success	如果退款状态为失败时, 会返回此字段

HTTP请求示例

请求参数

响应参数(成功)

响应参数(失败)

SDK请求示例

提示

使用SDK可以简化接入支付的速度