通用场景
商户可使用该接口查询自已通过alipay.trade.refund提交的退款请求是否执行成功。
注意：
1. 该接口的返回码10000，仅代表本次查询操作成功，不代表退款成功，当接口返回的refund_status值为refund_success时表示退款成功，否则表示退款没有执行成功。
2. 如果退款未成功，商户可以调用退款接口重试，重试时请务必保证退款请求号和退款金额一致，防止重复退款。
3. 发起退款查询接口的时间不能离退款请求时间太短，建议之间间隔10秒以上。
2. 如果退款未成功，商户可以调用退款接口重试，重试时请务必保证退款请求号和退款金额一致，防止重复退款。
3. 发起退款查询接口的时间不能离退款请求时间太短，建议之间间隔10秒以上。
公共请求参数
业务请求参数
out_request_no必选string(64)
【描述】退款请求号。
请求退款接口时，传入的退款请求号，如果在退款请求时未传入，则该值为创建交易时的商户订单号。
【示例值】hz01rf001
以下参数 二选一 传入
trade_nostring(64)
【描述】支付宝交易号。
和商户订单号不能同时为空
【示例值】2021081722001419121412730660
out_trade_nostring(64)
【描述】商户订单号。
订单支付时传入的商户订单号,和支付宝交易号不能同时为空。 trade_no,out_trade_no如果同时存在优先取trade_no
【示例值】2014112611001004680073956707
query_options可选string[](1024)
【描述】查询选项，商户通过上送该参数来定制同步需要额外返回的信息字段，数组格式。枚举支持：
refund_detail_item_list：本次退款使用的资金渠道；
gmt_refund_pay：退款执行成功的时间；
deposit_back_info：银行卡冲退信息；
【枚举值】
本次退款使用的资金渠道: refund_detail_item_list
退款执行成功的时间: gmt_refund_pay
银行卡冲退信息: deposit_back_info
【示例值】["refund_detail_item_list"]
常见请求示例
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.trade.fastpay.refund.query&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={
"trade_no":"2021081722001419121412730660",
"out_trade_no":"2014112611001004680073956707",
"out_request_no":"hz01rf001",
"query_options":[
"refund_detail_item_list"
]
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
trade_no特殊可选string(64)
【描述】支付宝交易号
【示例值】2014112611001004680073956707
out_trade_no特殊可选string(64)
【描述】创建交易传入的商户订单号
【示例值】20150320010101001
out_request_no特殊可选string(64)
【描述】本笔退款对应的退款请求号
【示例值】20150320010101001
total_amount特殊可选price(11)
【描述】该笔退款所对应的交易的订单金额。单位：元。
【示例值】100.20
refund_amount特殊可选price(11)
【描述】本次退款请求，对应的退款金额。单位：元。
【示例值】12.33
refund_status特殊可选string(32)
【描述】退款状态。枚举值：
refund_success 退款处理成功；
未返回该字段表示退款请求未收到或者退款失败；
注：如果退款查询发起时间早于退款时间，或者间隔退款发起时间太短，可能出现退款查询时还没处理成功，后面又处理成功的情况，建议商户在退款发起后间隔10秒以上再发起退款查询请求。
【枚举值】
退款处理成功: refund_success
【示例值】refund_success
refund_royaltys特殊可选refundroyaltyresult[]
【描述】退分账明细信息，当前仅在直付通产品中返回。
refund_amount必选price(9)
【描述】退分账金额。单位：元。
【示例值】10
result_code必选string(32)
【描述】退分账结果码
【示例值】success
royalty_type可选string(32)
【描述】分账类型.
字段为空默认为普通分账类型transfer
【枚举值】
普通分账类型: transfer
补差分账类型: replenish
【示例值】transfer
trans_out可选string(28)
【描述】转出人支付宝账号对应用户id
【示例值】2088102210397302
trans_out_email可选string(64)
【描述】转出人支付宝账号
【示例值】alipay-test03@alipay.com
trans_in可选string(28)
【描述】转入人支付宝账号对应用户id
【示例值】2088102210397302
trans_in_email可选string(64)
【描述】转入人支付宝账号
【示例值】zen_gwen@hotmail.com
ori_trans_out｜商户请求的转出账号可选string(28)
【描述】商户请求的转出账号
【示例值】2088111111111111
ori_trans_in｜商户请求的转入账号可选string(28)
【描述】商户请求的转入账号
【示例值】2088111111111111
gmt_refund_pay特殊可选date(32)
【描述】退款时间。默认不返回该信息，需要在入参的query_options中指定"gmt_refund_pay"值时才返回该字段信息。
【示例值】2014-11-27 15:45:57
refund_detail_item_list特殊可选tradefundbill[]
【描述】本次退款使用的资金渠道；
默认不返回该信息，需要在入参的query_options中指定"refund_detail_item_list"值时才返回该字段信息。
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
send_back_fee特殊可选string(11)
【描述】本次商户实际退回金额；单位：元。
默认不返回该信息，需要在入参的query_options中指定"refund_detail_item_list"值时才返回该字段信息。
【示例值】88
deposit_back_info特殊可选depositbackinfo
【描述】银行卡冲退信息；
默认不返回该信息，需要在入参的query_options中指定"deposit_back_info"值时才返回该字段信息。
has_deposit_back可选string(10)
【描述】是否存在银行卡冲退信息。
【示例值】true
dback_status可选string(8)
【描述】银行卡冲退状态。s-成功，f-失败，p-处理中。银行卡冲退失败，资金自动转入用户支付宝余额。
【示例值】s
dback_amount可选price(9)
【描述】银行卡冲退金额。单位：元。
【示例值】1.01
bank_ack_time可选string(32)
【描述】银行响应时间，格式为yyyy-mm-dd hh:mm:ss
【示例值】2020-06-02 14:03:48
est_bank_receipt_time可选string(32)
【描述】预估银行到账时间，格式为yyyy-mm-dd hh:mm:ss
【示例值】2020-06-02 14:03:48
refund_voucher_detail_list特殊可选voucherdetail[]
【描述】本交易支付时使用的所有优惠券信息。 只有在query_options中指定refund_voucher_detail_list时才返回该字段信息。
【必选条件】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
pre_auth_cancel_fee｜撤销的预授权金额特殊可选string(12)
【描述】当用户使用芝麻信用先享后付时，且当前的操作为预授权撤销动作时，会返回该字段，代表当前撤销的预授权金额，单位元。
【必选条件】当用户使用芝麻信用先享后付时，且当前的操作为预授权撤销动作时，会返回该字段。
【示例值】12.45
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
deposit_back_info_list可选depositbackinfo[]
【描述】银行卡冲退信息列表。
默认不返回该信息，需要在入参的query_options中指定"deposit_back_info_list"值时才返回该字段信息。
has_deposit_back可选string(10)
【描述】是否存在银行卡冲退信息。
【示例值】true
dback_status可选string(8)
【描述】银行卡冲退状态。s-成功，f-失败，p-处理中。银行卡冲退失败，资金自动转入用户支付宝余额。
【示例值】s
dback_amount可选price(9)
【描述】银行卡冲退金额
【示例值】1.01
bank_ack_time可选string(32)
【描述】银行响应时间，格式为yyyy-mm-dd hh:mm:ss
【示例值】2020-06-02 14:03:48
est_bank_receipt_time可选string(32)
【描述】预估银行到账时间，格式为yyyy-mm-dd hh:mm:ss
【示例值】2020-06-02 14:03:48
响应示例
正常示例
异常示例
{
"alipay_trade_fastpay_refund_query_response": {
"code": "10000",
"msg": "success",
"trade_no": "2014112611001004680073956707",
"out_trade_no": "20150320010101001",
"out_request_no": "20150320010101001",
"total_amount": "100.20",
"refund_amount": "12.33",
"refund_status": "refund_success",
"refund_royaltys": [
{
"refund_amount": "10",
"royalty_type": "transfer",
"result_code": "success",
"trans_out": "2088102210397302",
"trans_out_email": "alipay-test03@alipay.com",
"trans_in": "2088102210397302",
"trans_in_email": "zen_gwen@hotmail.com",
"ori_trans_out": "2088111111111111",
"ori_trans_in": "2088111111111111"
}
],
"gmt_refund_pay": "2014-11-27 15:45:57",
"refund_detail_item_list": [
{
"fund_channel": "alipayaccount",
"amount": "10",
"real_amount": "11.21",
"fund_type": "debit_card"
}
],
"send_back_fee": "88",
"deposit_back_info": {
"has_deposit_back": "true",
"dback_status": "s",
"dback_amount": "1.01",
"bank_ack_time": "2020-06-02 14:03:48",
"est_bank_receipt_time": "2020-06-02 14:03:48"
},
"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"
}
]
}
],
"deposit_back_info_list": [
{
"has_deposit_back": "true",
"dback_status": "s",
"dback_amount": "1.01",
"bank_ack_time": "2020-06-02 14:03:48",
"est_bank_receipt_time": "2020-06-02 14:03:48"
}
],
"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.enterprise_pay_biz_error | 因公付业务异常 | 重新发起查询请求，如果多次重试后仍返回同样的错误，请联系支付宝小二处理 |
| acq.invalid_parameter | 参数无效 | 请根据接口返回的错误信息，检查请求参数，修改后重新发起请求 |
| acq.system_error | 系统错误 | 重新发起查询请求，如果多次重试后还是返回系统错误，请联系支付宝小二处理 |
| acq.trade_not_exist | 交易不存在 | 请确认传入的外部订单号或交易号是否正确 |
| trade_not_exist | 查询退款的交易不存在 | 确认交易号是否为正确的支付宝交易号，修改后重新查询 |