开发者社区
社区提问意见反馈
开发者钉组织
扫描二维码
加入支付宝开发者钉组织
文档中心
网页&移动应用 
支付产品
当面付
app支付
接入指南
api 列表
交易
账单
相关资料
手机网站支付
电脑网站支付
刷脸付
预授权支付
商家扣款
订单码支付
私域产品
公域产品
营销产品
资金产品
会员产品
信用产品
安全产品
广告产品
其他通用产品
开发 > 服务端 > 支付产品 > app支付 > api 列表 > 交易 > 统一收单交易退款接口
已更新
文档更新记录 >
收藏
订阅更新
我的文档
设置
接入检测
即可查看检测结果)
若有未通过的接入检测项,接口将无法调通
当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,支付宝将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。
交易超过约定时间(签约时设置的可退款时间)的订单无法进行退款。
支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的订单号和设置不同的退款请求号。一笔退款失败后重新提交,要保证重试时退款请求号不能变更,防止该笔交易重复退款。
同一笔交易累计提交的退款金额不能超过原始交易总金额。

公共请求参数

参数类型是否必选最大长度描述示例值
app_idstring必选32
支付宝分配给开发者的应用id
2014072300007148
methodstring必选128
接口名称
alipay.trade.refund
formatstring可选40
仅支持json
json
charsetstring必选10
请求使用的编码格式,如utf-8,gbk,gb2312等
utf-8
sign_typestring必选10
商户生成签名字符串所使用的签名算法类型,目前支持rsa2和rsa,推荐使用rsa2
rsa2
signstring必选344
商户请求参数的签名串,详见签名
详见示例
timestampstring必选19
发送请求的时间,格式"yyyy-mm-dd hh:mm:ss"
2014-07-24 03:07:50
versionstring必选3
调用的接口版本,固定为:1.0
1.0
app_auth_tokenstring可选40
biz_contentstring必选
请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

业务请求参数

refund_amount必选price(16)
【描述】退款金额。 需要退款的金额,该金额不能大于订单金额,单位为元,支持两位小数。 注:如果正向交易使用了营销,该退款金额包含营销金额,支付宝会按业务规则分配营销和买家自有资金分别退多少,默认优先退买家的自有资金。如交易总金额100元,用户支付时使用了80元自有资金和20元无资金流的营销券,商家实际收款80元。如果首次请求退款60元,则60元全部从商家收款资金扣除退回给用户自有资产;如果再请求退款40元,则从商家收款资金扣除20元退回用户资产以及把20元的营销券退回给用户(券是否可再使用取决于券的规则配置)。
【示例值】200.12
以下参数 二选一 传入
out_trade_nostring(64)
【描述】商户订单号。 订单支付时传入的商户订单号,商家自定义且保证商家系统中唯一。与支付宝交易号 trade_no 不能同时为空。
【示例值】20150320010101001
trade_nostring(64)
【描述】支付宝交易号。 和商户订单号 out_trade_no 不能同时为空,两者同时存在时,优先取值trade_no
【示例值】2014112611001004680073956707
refund_reason可选string(256)
【描述】退款原因说明。 商家自定义,将在会在商户和用户的pc退款账单详情中展示
【示例值】正常退款
out_request_no可选string(64)
【描述】退款请求号。 标识一次退款请求,需要保证在交易号下唯一,如需部分退款,则此参数必传。 注:针对同一次退款请求,如果调用接口失败或异常了,重试时需要保证退款请求号不能变更,防止该笔交易重复退款。支付宝会保证同样的退款请求号多次请求只会退一次。
【必选条件】部分退款时必选
【示例值】hz01rf001
refund_goods_detail可选refundgoodsdetail[]
【描述】退款包含的商品列表信息
goods_id必选string(32)
【描述】商品编号。 对应支付时传入的goods_id
【示例值】apple-01
refund_amount必选price(9)
【描述】该商品的退款总金额,单位为元
【示例值】19.50
out_certificate_no_list|外部凭证编号列表可选string[](128)
【描述】外部商品凭证编号列表
【示例值】["202407013232143241231243243423"]
out_item_id可选string(64)
【描述】商家侧小程序商品id,对应支付时传入的out_item_id
【示例值】outitem_01
out_sku_id可选string(64)
【描述】商家侧小程序商品sku id,对应支付时传入的out_sku_id
【示例值】outsku_01
refund_royalty_parameters可选openapiroyaltydetailinfopojo[]
【描述】退分账明细信息。 注: 1.当面付且非直付通模式无需传入退分账明细,系统自动按退款金额与订单金额的比率,从收款方和分账收入方退款,不支持指定退款金额与退款方。 2.直付通模式,电脑网站支付,手机 app 支付,手机网站支付产品,须在退款请求中明确是否退分账,从哪个分账收入方退,退多少分账金额;如不明确,默认从收款方退款,收款方余额不足退款失败。不支持系统按比率退款。
royalty_type可选string(32)
【描述】分账类型.
【枚举值】
分账: transfer
营销补差: replenish
【注意事项】为空默认为分账transfer;
【示例值】transfer
trans_out可选string(16)
【描述】支出方账户。如果支出方账户类型为userid,本参数为支出方的支付宝账号对应的支付宝唯一用户号,以2088开头的纯16位数字;如果支出方类型为loginname,本参数为支出方的支付宝登录号。 泛金融类商户分账时,该字段不要上送。
【示例值】2088101126765726
trans_out_type可选string(64)
【描述】支出方账户类型。
【枚举值】
支付宝账号对应的支付宝唯一用户号: userid
支付宝登录号: loginname
【注意事项】泛金融类商户分账时,该字段不要上送。
【示例值】userid
trans_in_type可选string(64)
【描述】收入方账户类型。
【枚举值】
支付宝账号对应的支付宝唯一用户号: userid
支付宝登录号: loginname
卡编号: cardaliasno
【示例值】userid
trans_in可选string(16)
【描述】收入方账户。如果收入方账户类型为userid,本参数为收入方的支付宝账号对应的支付宝唯一用户号,以2088开头的纯16位数字;如果收入方类型为cardaliasno,本参数为收入方在支付宝绑定的卡编号;如果收入方类型为loginname,本参数为收入方的支付宝登录号;
【示例值】2088101126708402
amount可选price(9)
【描述】分账的金额,单位为元
【示例值】0.1
desc可选string(1000)
【描述】分账描述
【示例值】分账给2088101126708402
royalty_scene可选string(256)
【描述】可选值:达人佣金、平台服务费、技术服务费、其他
【示例值】达人佣金
trans_in_name可选string(64)
【描述】分账收款方姓名,上送则进行姓名与支付宝账号的一致性校验,校验不一致则分账失败。不上送则不进行姓名校验
【示例值】张三
query_options可选string[](1024)
【描述】查询选项。 商户通过上送该参数来定制同步需要额外返回的信息字段,数组格式。
【枚举值】
本次退款使用的资金渠道: refund_detail_item_list
银行卡冲退信息: deposit_back_info
本次退款退的券信息: refund_voucher_detail_list
【示例值】["refund_detail_item_list"]
related_settle_confirm_no可选string(64)
【描述】针对账期交易,在确认结算后退款的话,需要指定确认结算时的结算单号。
【示例值】2024041122001495000530302869
常见请求示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.trade.refund&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
 -f 'app_auth_token=${app_auth_token}' \
 -f 'biz_content={
	"out_trade_no":"20150320010101001",
	"trade_no":"2014112611001004680073956707",
	"refund_amount":"200.12",
	"refund_reason":"正常退款",
	"out_request_no":"hz01rf001",
	"refund_goods_detail":[
		{
			"out_sku_id":"outsku_01",
			"out_item_id":"outitem_01",
			"goods_id":"apple-01",
			"refund_amount":"19.50",
			"out_certificate_no_list":[
				"202407013232143241231243243423"
			]
		}
	],
	"refund_royalty_parameters":[
		{
			"amount":"0.1",
			"trans_in":"2088101126708402",
			"royalty_type":"transfer",
			"trans_out":"2088101126765726",
			"trans_out_type":"userid",
			"royalty_scene":"达人佣金",
			"trans_in_type":"userid",
			"trans_in_name":"张三",
			"desc":"分账给2088101126708402"
		}
	],
	"query_options":[
		"refund_detail_item_list"
	],
	"related_settle_confirm_no":"2024041122001495000530302869"
}' 
说明:本示例仅供参考。

公共响应参数

参数类型是否必选最大长度描述示例值
codestring必选-
网关返回码,
40004
msgstring必选-
网关返回码描述,
business failed
sub_codestring可选-
业务返回码,参见具体的api接口文档
acq.trade_has_success
sub_msgstring可选-
业务返回码描述,参见具体的api接口文档
交易已被支付
signstring必选-
签名,
dzxh8eetuahoye3w1j poiphfdxoybfunn1lket/v7p4zjdyojwea6izs6hz0ydw5cp/viufub5i0/v5wens3oyr8zredqo6d futdlhdc efyckiqhbxizgngpdpdfp1pis7bdhhzrszhbrqb7o4k3dxc aanfauu4v6zdwczo=

业务响应参数

trade_no必选string(64)
【描述】支付宝交易号
【示例值】2013112011001004330000121536
out_trade_no必选string(64)
【描述】商户订单号
【示例值】6823789339978248
buyer_logon_id必选string(100)
【描述】用户的登录id
【示例值】159****5620
refund_fee必选price(11)
【描述】退款总金额。单位:元。 指该笔交易累计已经退款成功的金额。
【示例值】88.88
refund_detail_item_list特殊可选tradefundbill[]
【描述】退款使用的资金渠道。 只有在签约中指定需要返回资金明细,或者入参的query_options中指定时才返回该字段信息。
fund_channel必选string(32)
【描述】交易使用的资金渠道,详见 支付渠道列表
【示例值】alipayaccount
amount必选price(32)
【描述】该支付工具类型所使用的金额。单位:元。
【示例值】10
real_amount可选price(11)
【描述】渠道实际付款金额
【示例值】11.21
fund_type可选string(32)
【描述】渠道所使用的资金类型,目前只在资金渠道(fund_channel)是银行卡渠道(bankcard)的情况下才返回该信息
【枚举值】
借记卡: debit_card
信用卡: credit_card
借贷合一卡: mixed_card
【示例值】debit_card
store_name特殊可选string(512)
【描述】交易在支付时候的门店名称
【必选条件】交易在支付时候的门店名称
【示例值】望湘园联洋店
buyer_user_id特殊可选string(28)
【描述】买家在支付宝的用户id
新商户建议使用buyer_open_id替代该字段。对于新商户,buyer_user_id字段未来计划逐步回收,存量商户可继续使用。如使用buyer_open_id,请确认 应用-开发配置-openid配置管理 已启用。无该配置项,可查看openid配置申请
【示例值】2088101117955611
buyer_open_id特殊可选string(128)
【描述】买家支付宝用户唯一标识  详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
send_back_fee特殊可选string(11)
【描述】本次商户实际退回金额。单位:元。 说明:如需获取该值,需在入参query_options中传入 refund_detail_item_list。
【示例值】1.8
pre_auth_cancel_fee|撤销的预授权金额特殊可选string(12)
【描述】当用户使用芝麻信用先享后付时,且当前的操作为预授权撤销动作时,会返回该字段,代表当前撤销的预授权金额,单位元。
【必选条件】当用户使用芝麻信用先享后付时,且当前的操作为预授权撤销动作时,会返回该字段。
【示例值】12.45
fund_change可选string(1)
【描述】本次退款是否发生了资金变化
【示例值】y
refund_hyb_amount可选string(11)
【描述】本次请求退惠营宝金额。单位:元。
【示例值】10.24
refund_charge_info_list可选refundchargeinfo[]
【描述】退费信息
refund_charge_fee|实退费用可选price(11)
【描述】实退费用。单位:元。
【示例值】0.01
switch_fee_rate|签约费率可选string(64)
【描述】签约费率
【示例值】0.01
charge_type|手续费类型可选string(64)
【描述】收单手续费trade,花呗分期手续hbfq,其他手续费charge
【示例值】trade
refund_sub_fee_detail_list|组合支付退费明细可选refundsubfee[]
【描述】组合支付退费明细
refund_charge_fee|实退费用可选price(11)
【描述】实退费用。单位:元。
【示例值】0.10
switch_fee_rate|签约费率可选string(64)
【描述】签约费率
【示例值】0.01
refund_voucher_detail_list可选voucherdetail[]
【描述】本交易支付时使用的所有优惠券信息。 只有在query_options中指定了refund_voucher_detail_list时才返回该字段信息。
id必选string(32)
【描述】券id
【示例值】2015102600073002039000002d5o
name必选string(64)
【描述】券名称
【示例值】xx超市5折优惠
type必选string(32)
【描述】券类型
【枚举值】
全场代金券: alipay_fix_voucher
折扣券: alipay_discount_voucher
单品优惠券: alipay_item_voucher
【注意事项】不排除将来新增其他类型的可能,商家接入时注意兼容性避免硬编码
【示例值】alipay_fix_voucher
amount必选price(8)
【描述】优惠券面额,它应该会等于商家出资加上其他出资方出资
【示例值】10.00
merchant_contribute可选price(8)
【描述】商家出资(特指发起交易的商家出资金额)
【示例值】9.00
other_contribute可选price(8)
【描述】其他出资方出资金额,可能是支付宝,可能是品牌商,或者其他方,也可能是他们的一起出资
【示例值】1.00
memo可选string(256)
【描述】优惠券备注信息
【示例值】学生专用优惠
template_id可选string(64)
【描述】券模板id
【示例值】20171030000730015359000emzp0
other_contribute_detail可选contributedetail[](512)
【描述】优惠券的其他出资方明细
contribute_type|出资方类型必选string(32)
【描述】出资方类型
【枚举值】
平台出资: platform
品牌商出资: brand
商圈出资 : mall
【注意事项】不排除将来新增其他类型的可能,商家接入时注意兼容性避免硬编码
【示例值】brand
contribute_amount必选price(8)
【描述】出资方金额
【示例值】8.00
purchase_buyer_contribute可选price(8)
【描述】如果使用的这张券是用户购买的,则该字段代表用户在购买这张券时用户实际付款的金额
【示例值】2.01
purchase_merchant_contribute可选price(8)
【描述】如果使用的这张券是用户购买的,则该字段代表用户在购买这张券时商户优惠的金额
【示例值】1.03
purchase_ant_contribute可选price(8)
【描述】如果使用的这张券是用户购买的,则该字段代表用户在购买这张券时平台优惠的金额
【示例值】0.82
响应示例
{
    "alipay_trade_refund_response": {
        "code": "10000",
        "msg": "success",
        "trade_no": "2013112011001004330000121536",
        "out_trade_no": "6823789339978248",
        "buyer_logon_id": "159****5620",
        "fund_change": "y",
        "refund_fee": "88.88",
        "refund_detail_item_list": [
            {
                "fund_channel": "alipayaccount",
                "amount": "10",
                "real_amount": "11.21",
                "fund_type": "debit_card"
            }
        ],
        "store_name": "望湘园联洋店",
        "buyer_user_id": "2088101117955611",
        "buyer_open_id": "074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5",
        "send_back_fee": "1.8",
        "refund_hyb_amount": "10.24",
        "refund_charge_info_list": [
            {
                "refund_charge_fee": "0.01",
                "switch_fee_rate": "0.01",
                "charge_type": "trade",
                "refund_sub_fee_detail_list": [
                    {
                        "refund_charge_fee": "0.10",
                        "switch_fee_rate": "0.01"
                    }
                ]
            }
        ],
        "refund_voucher_detail_list": [
            {
                "id": "2015102600073002039000002d5o",
                "name": "xx超市5折优惠",
                "type": "alipay_fix_voucher",
                "amount": "10.00",
                "merchant_contribute": "9.00",
                "other_contribute": "1.00",
                "memo": "学生专用优惠",
                "template_id": "20171030000730015359000emzp0",
                "other_contribute_detail": [
                    {
                        "contribute_type": "brand",
                        "contribute_amount": "8.00"
                    }
                ],
                "purchase_buyer_contribute": "2.01",
                "purchase_merchant_contribute": "1.03",
                "purchase_ant_contribute": "0.82"
            }
        ],
        "pre_auth_cancel_fee": "12.45"
    },
    "sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}
说明:本示例仅供参考。

公共错误码

业务错误码

错误码错误描述凯发app官方网站的解决方案
acq.alloc_amount_validate_error退分账金额超限
请调整退分账金额后重试
acq.buyer_enable_status_forbid买家状态异常
联系支付宝小二确认买家状态异常原因,或者可联系买家进行线下退款处理
acq.buyer_error买家状态异常。
联系支付宝小二确认买家状态异常原因,或者可联系买家进行线下退款处理
acq.buyer_not_exist买家不存在
买家已经注销账号,建议联系买家进行线下退款处理
acq.currency_not_support退款币种不支持
请确认传入的退款币种是否正确
acq.customer_validate_error账户已注销或者被冻结
请查询账户状态:1. 如果账户已注销,请线下处理;2. 如果账户已冻结,请联系支付宝小二确认冻结原因。
acq.discordant_repeat_request请求信息不一致
退款请求号对应的退款已经执行成功,且本次请求的退款金额与之前请求的金额不一致,请检查传入的退款金额是否正确。 或者通过退款查询接口获取退款执行结果。
acq.enterprise_pay_biz_error因公付业务异常
如果提示“当前交易不含企业出资”,请确认交易是否包含企业出资,如果不包含则接口入参不能指定enterprise_pay_info参数,如果确认包含则联系支付宝核实。 如果提示“无效企业退款金额”,请检查指定的企业退款金额是否超过当前交易企业支付的金额。 其它情况,请联系支付宝小二。
acq.invalid_parameter参数无效
请根据接口返回的错误信息,检查请求参数,修改后重新发起请求
acq.not_allow_partial_refund不支持部分退款
由于交易使用了特定的优惠券等场景,该笔交易不支持部分退款,请对交易进行全额退款或者联系买家进行线下退款处理
acq.online_trade_voucher_not_allow_refund交易不允许退款
此交易中核销了购买的代金券,不允许进行退款,可联系买家进行线下退款处理
acq.overdraft_agreement_not_match垫资退款接口传入模式和签约配置不一致
请检查垫资退款合约中的出资方式,修改合约或接口传参后重试
acq.overdraft_assign_account_invalid垫资退款出资账号和商户信息不一致
垫资退款出资账号必须为商户名下支付宝账号,请更换出资账号后重试
acq.reason_trade_been_freezen请求退款的交易被冻结
联系支付宝小二,确认该笔交易的具体情况
acq.reason_trade_refund_fee_err退款金额无效
同一笔交易累计请求的退款金额不能大于交易总金额,请检查退款请求的金额是否正确。
acq.reason_trade_status_invalid交易状态异常
查询交易,确认交易是否是支付成功状态,是的话可联系支付宝小二确认交易状态
acq.refund_account_not_exist退款出资账号不存在或账号异常
检查退款出资账号状态,账号正常后重试
acq.refund_amt_not_equal_total退款金额超限
1、请检查退款金额是否正确,请求的退款金额不能大于交易总金额; 2、如果不是全额退款,退款请求号必填,请检查是否传入了退款请求号;
acq.refund_charge_error退收费异常
请过一段时间后再重试发起退款
acq.refund_fee_error交易退款金额有误
请检查传入的退款金额是否正确
acq.refund_royalty_payee_account_not_exist退分账收入方账户不存在
退分账收入方账户不存在,请确认收入方账号是否正确,更换账号后重新发起
acq.seller_balance_not_enough卖家余额不足
商户支付宝账户充值后重新发起退款即可
acq.system_error系统错误
接口返回系统错误情况下,当前请求的退款可能成功也可能失败。 1、请使用相同的参数再次重试调用,需要保证退款请求号和退款金额不能变更。如果前一次退款请求已经处理成功,接口会幂等返回成功;如果前一次退款请求没有成功,接口会重试执行退款操作; 2、或者通过退款查询接口查询退款执行结果,发起退款查询接口需要保证间隔退款请求大于5秒以上;
acq.trade_has_close交易已关闭
该交易已关闭,不能再进行退款,请确认请求退款的交易是否未支付或者已完成退款
acq.trade_has_finished交易已完结
该交易已完结(已超过退款期限),不允许进行退款(即使重试也无法成功),建议联系买家进行线下退款处理。
acq.trade_not_allow_refund当前交易不允许退款
检查当前交易的状态是否为交易成功状态以及签约的退款属性是否允许退款,确认后,重新发起请求
acq.trade_not_exist交易不存在
检查请求中的交易号和商户订单号是否正确,确认后重新发起
acq.trade_settle_error交易结算异常
请检查传入的退结算项信息是否正确,如果正确请联系支付宝小二
acq.trade_status_error交易状态非法
查询交易,确认交易是否已经付款
acq.user_not_match_err交易用户不匹配
请联系支付宝小二处理
内容没有解决您的问题?您还可以前往 或 寻求帮助
凯发k8官方网娱乐官方 copyright © 2022 支付宝(杭州)信息技术有限公司  | icp证浙b2-20160559
该文档对你是否有帮助?
当前页面目录
为开发者能享受更简单的协议处理逻辑、更丰富的开源工具配套、更低的接口响应时延,支付宝开放平台推出符合oas3.0规范的,助力开发体验。新版本文档请点击“查看v3版本”进行访问。