Use case:
Within three months of the payment, if there is a need to refund the buyer, the merchant could return the fund to the buyer with this API. When Alipay receives the request, it will validate the request and refund the user to the original funding channel, if applicable.
| Parameter | Type | Mandatory | Length | Description | Sample |
|---|---|---|---|---|---|
| app_id | String | Y | 32 | An app id assigned to the developer by Alipay | 2014072300007148 |
| method | String | Y | 128 | api name | Alipay.data.dataservice.bill.downloadurl.query |
| charset | String | Y | 10 | The char set for request use, like utf-8, gbk, gb2312, etc. | utf-8 |
| sign_type | String | Y | 10 | The type of signature algorithm used by the merchant to generate the signature string. Currently RSA and RSA2 are supported. | RSA2 |
| sign | String | Y | 256 | Signature string | |
| timestamp | String | Y | 19 | The sending time of the request, formatting in “yyyy-MM-dd HH:mm:ss” | 2014-07-24 03:07:50 |
| version | String | Y | 3 | The version of this API, hard coded as 1.0 for now. | 1.0 |
| app_auth_token | String | N | 40 | Please refer to the section “application authorization” |
| Parameter | Type | Mandatory | Length | Description | Sample |
|---|---|---|---|---|---|
| trade_no | String | Y | 64 | Alipay transaction id. | 2014112611001004680073956707 |
| refund_amount | String | Y | 9 | The amount to be refunded, in CNY. It should not be greater than the original payment amount. The number should be in the form of 0 or 2 digits after the decimal point. | 200.12 |
| out_request_no | String | N | 64 | The unique id for the refund request. It must be unique in the merchant system. | HZ01RF001 |
| refund_reason | String | N | 128 | The refund reason. | 正常退款 |
| store_id | String | N | 32 | The store id. | NJ_S_001 |
| terminal_id | String | N | 32 | The terminal id. | NJ_T_001 |
Sample:
method=alipay.trade.refund,
app_id=2014072300007148,
charset=utf-8,
sign_type=RSA2,
sign=85bf83f78d5cefb804bd805532fc688e,
timestamp=2014-07-24 03:07:50,
biz_content={
"trade_no": "2014112611001004680073956707",
"refund_amount": "77.77",
"out_request_no": "HZ01RF001",
"refund_reason": "O2O当面付退款",
"store_id": "ST_001",
"terminal_id": "T_001"
}
| Parameter | Type | Mandatory | Length | Description | Sample |
|---|---|---|---|---|---|
| trade_no | String | N | 64 | Alipay transaction id. | 2013112011001004330000121536 |
| out_trade_no | String | N | 64 | out_trade_no in the payment request. | 6823789339978248 |
| buyer_user_id | String | N | 16 | The user id associated with the buyer’s Alipay account, in the format of 16 digit number starting with “2088”. | 2088102122524333 |
| buyer_logon_id | String | N | 100 | The buyer’s Alipay account id，part of which will be replaced by ‘*’. | 159****5620 |
| fund_change | String | Y | 1 | For the same refund request, if the last refund request succeeds, the result of last request will be returned. This flag will indicate if there is fund movement associated with the request： Y——fund moved； N——No fund movement. |
Y |
| refund_fee | String | N | 9 | The total amount of the refund, in CNY. The number should be in the form of 0 or 2 digits after the decimal point. | 2.58 |
| gmt_refund_pay | Date | N | 32 | Refund time in the format of “ yyyy-MM-dd HH:mm:ss”. | 2014-11-27 15:45:57 |
| refund_detail_item_list | List | Y | The details of the refund, including all the funding channel information in JSON format. For more information, please refer to “Funding Channel Details” | ||
| store_name | String | N | 512 | The store name | 证大五道口店 |
Sample:
{
"alipay_trade_refund_response": {
"code": "10000",
"msg": "处理成功",
"trade_no": "2013112011001004330000121536",
"out_trade_no": "6823789339978248",
"buyer_user_id": "2088102122524333",
"buyer_logon_id": "159****5620",
"fund_change": "Y",
"refund_fee": "2.58",
"send_back_fee": "2.08",
"gmt_refund_pay": "2014-11-27 15:45:57"
"store_name": "证大五道口店"
},
"sign": "jfAz0Yi0OUvAPqYTzA0DLysx0ri++yf7o/lkHOHaG1Zy2fHBf3j4WM+sJWHZUuyInt6V+wn+6IP9AmwRTKi+GGdWjPrsfBjXqR7H5aBnLhMsAltV7v4cYjhuguAqh4WkaJO6v6CfdybDpzHlxE6Thoucnad+OsjdCXkNd1g3UuU="
}
{
"alipay_trade_refund_response": {
"code": "40004",
"msg": "处理失败",
"sub_code": "ACQ.REASON_TRADE_BEEN_FREEZEN",
"sub_desc": "请求退款的交易被冻结"
},
"sign": "jfAz0Yi0OUvAPqYTzA0DLysx0ri++yf7o/lkHOHaG1Zy2fHBf3j4WM+sJWHZUuyInt6V+wn+6IP9AmwRTKi+GGdWjPrsfBjXqR7H5aBnLhMsAltV7v4cYjhuguAqh4WkaJO6v6CfdybDpzHlxE6Thoucnad+OsjdCXkNd1g3UuU="
}
| Name | Description | Solution |
|---|---|---|
| ACQ.SYSTEM_ERROR | System time out | Retry with the same parameter |
| ACQ.INVALID_PARAMETER | At least one of the parameters is not valid. | Examine the request parameters and resend the request after fixing the issue. |
| ACQ.SELLER_BALANCE_NOT_ENOUGH | The merchant does not have enough balance to cover the refund. | The seller could add fund to the account and refund. |
| ACQ.REFUND_AMT_NOT_EQUAL_TOTAL | The total refund amount is greater than the original payment amount. | Check if the refund amount is correct. Retry the refund with the correct amount. |
| ACQ.REASON_TRADE_BEEN_FREEZEN | The payment is restricted and could not be cancelled. | Please contact Alipay CS to get the transaction status. |
| ACQ.TRADE_NOT_EXIST | The payment does not exist for the refund. | Examine if the trade_no is correct and retry after correction. |
| ACQ.TRADE_HAS_FINISHED | The trade is finished and no refund is allowed. The trade is finished and no refund is allowed. | Examine if the payment info is correct for the refund. |
| ACQ.TRADE_STATUS_ERROR | The current payment status does not allow refund. | Call “query” API and confirm if the payment is complete. |
| ACQ.DISCORDANT_REPEAT_REQUEST | Duplicated refund with inconsistent request info. | Examine if the refund was done earlier with the same ‘out_request_no”. Or retry with a different ‘out_request_no”. |
| ACQ.REASON_TRADE_REFUND_FEE_ERR | The refund amount is over the allowed amount. | Check if the refund amount is correct. Retry the refund with the correct amount. |
