alipay.acquire.refund
Auto-debit Acquiring refund Interface-- alipay.acquire.refundThis interface can be used by merchant to refund the transaction.
Request
Service address
Environment | HTTPS request URL |
Production environment | |
Test environment |
Request parameters
| Parameter | Type(length) | Description | Required | Example |
| Basic parameters | ||||
| service | String | Service Name | Y | alipay.acquire.refund |
| partner | String(16) | Partner ID that is composed of 16 digits beginning with 2088. | Y | 2088101125328850 |
| _input_charset | String | The charset with which the request data is encoded. UTF-8 is supported. | Y | utf-8 |
| sign_type | String | Sign type. DSA, RSA, and MD5 are supported. Use uppercase. | Y | MD5 |
| sign | String | Sign value | Y | 363a752668ee2b3b8f1 24c623bd028ad |
| alipay_ ca_req uest | String | Signature type. 1: Certificate signature 2: Other key signatures If this is null, the default value shall be 2. | N | 2 |
| notify_url | String(190) | The URL for receiving asynchronous notifications after the payment is completed. | N | http://api.test.alipay.net/atinterface/receive_notify.htm |
| Business parameters | ||||
| out_trade_no | String(64) | Unique order No. in Alipay’s merchant’s website | Y | HZ0120131127001 |
| refund_amount | number(9,2) | The amount refunded shall not be greater than order amount. Full refund shall be consistent with order amount. | Y | 200.00 |
| trans_currency | String(8) | The currency used for refund pricing. It should be either CNY or the trans_currency used for purchasing. Default value is CNY | N | CNY |
| trade_no | String(64) | The trade serial number of the trade in Alipay system.16 bits at least and 64 bits at most. If out_trade_no and trade_no are transmitted at the same time, trade_no shall govern. | N | 2013112611001004680073956707 |
| sync_flag | String(1) | The refund request is processed synchronously or asynchronously. Value: Y or N. Default value is N, which is processed asynchronously. | N | N |
| out_request_no | String(64) | Merchant’s refund request No. is used to identify the refund request in this trade.If this parameter is not transmitted, out_trade_no shall be filled out as the value of this parameter and at the same time it is deemed that this request is full refund request. The refund amount shall be the same as the payment amount. | N | HZ01RF001 |
| operator_type | String(1) | Operator type:0: operator of Alipay1: operator of merchantIf other value or no value is transmitted, it shall be deemed to be 1. | N | 1 |
| operator_id | String(28) | Seller’s operator ID | N | OP001 |
| refund_reason | String(128) | Refund reason explanation | N | Normal refund |
| ref_ids | String(256) | Business reference ID set is used for placing merchant’s refund order No., refund serial No., etc. It shall be in json format. Please refer to ref_ids for details. | N | [{"id_type":"orig_out_req uest_no","id":"HZ0001"},{"id_type":"orig_out_order_no","id":"HZ0001"}] |
| extend_params | String(128) | Be used for transferring refund business information. Only when merchant and Alipay prescribed for passing this parameter and the parameter meaning, this parameter is valid. | N | {"STORE_ID":"BJ_ZZ_001","STORE_TYPE":"0"} |
ref_ids
| Parameter | Type(length) | Description | Required | Example |
| id_type | String | Extended ID type: orig_out_order_no: merchant’s original refund order No. orig_out_request_no: merchant’s original refund request serial No. | Y | orig_out_order_no |
| id | String | Extended ID value | Y | HZ0001 |
extend_params
| Parameter | Type(length) | Description | Required | Example |
| STORE_TYPEP | String | Store type. 0: Alipay store 1: merchant store | N | 0 |
| STORE_ID | String | Store id, need to combine with STORE_TYPE. Merchant need to confirm that the store id is exit under the relevant store type. | N | BJ_ZZ_001 |
| TERMINAL_ID | String | The terminal device that used for submit request. This parameter is indispensable if use promotions. | N | A80001 |
Response
| Parameter | Type(length) | Description | Required | Example |
| Basic parameter | ||||
| is_success | String | Request succeeds or not. Successful request does not mean the business is accepted and processed successfully. T means success F means failure | Y | T |
| sign_type | String | Sign type. DSA, RSA, and MD5 are supported. Use uppercase. | N | MD5 |
| sign | String | Sign value | N | fc209d86b57b2adb23254a897ebaa7d9 |
| error | String | This parameter does not exist if request succeeds; This parameter will be error code if request fails. | N | ILLEGAL_SIGN |
| result_code | String(32) | Response code of refund processing result. SUCCESS: successful refund INPROCESS: the request is accepted; refund in process. FAIL: unsuccessful refund UNKNOWN: unknown result | Y | SUCCESS |
| trade_no | String(64) | Trade number of the trade in Alipay system16 bits at least and 64 bits at most | N | 2013112011001004330000121536 |
| out_trade_no | String(64) | Unique order ID in order system in corresponding merchant’s website other than Alipay trade number.Uniqueness of this parameter in merchant’s website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape. | N | 6823789339978248 |
| buyer_user_id | String(24) | Unique Alipay user ID corresponding to Buyer’s Alipay logon ID.16 numbers beginning with 2088 | N | 2088102122524333 |
| buyer_logon_id | String(100) | Buyer’s Alipay logon ID, may be email or phone number. | N | 159****5620 |
| fund_change | String(1) | In respect of refund request of the same merchant, if the refund has been conducted, the result of last refund will be returned directly. At the same time, identification of whether capital change happens or not will be returned. Y: capital change happened in this refund request; N: capital change does not happen in this refund request | N | Y |
| refund_fee | Number | The actual refund amount, the unit is RMB. | N | 1.00 |
| trans_currency | String(8) | The currency used for refund pricing. It should be either CNY or the trans_currency used for purchasing. | N | CNY |
| gmt_refund_pay | Date | Refund date, the format as below:yyyy-MM-dd HH:mm:ss | N | 2013-11-27 15:45:57 |
| refund_detail_item_list | List | Refund amount of return channel, the XML format, and can return multiple refund channel child node <TradeFundBil>, the parameter of the node contains , please refer to refund_detail_item_list. | N | Refer to “5.3 Refund Channel List” |
| detail_error_code | String(48) | Give cause description to the response code returned. If the response code of result_code is SUCCESS, this parameter shall not be returned. | N | TRADE_STATUS_ER ROR |
| detail_error_des | String(64) | Give literal statement as to the detailed error code. If the response code of result_code is SUCCESS, this parameter shall not be returned. | N | Trade status is illegal. |
refund_detail_item_list
| Parameter | Type(length) | Description | Required | Example |
| fund_channel | String | Refund channel, refer to refund channel | N | ALIPAYACCOUNT |
| amount | String | The amount that Using the specified channels refund, the unit is RMB. | N | 70.00 |
Error codes
Business errors
| Error code | Description |
| INVALID_PARAMETER | Parameter is invalid. |
| TRADE_ROLE_ERROR | There is no right to refund or withdraw this trade. |
| DISCORDANT_REPEAT_REQUEST | The refund amount or the amount specified in withdrawal order of the same trade is inconsistent. |
| TRADE_HAS_CLOSE | The trade has been closed. |
| REASON_TRADE_BEEN_FREEZEN | The trade has been frozen. |
| BUYER_ERROR | The buyer does not exist. |
| SELLER_ERROR | The seller does not exist. |
| TRADE_NOT_EXIST | The trade does not exist. |
| TRADE_STATUS_ERROR | The trade status is illegal. |
| TRADE_HAS_FINISHED | The trade has been finished. |
| REFUND_AMT_NOT_EQUAL_TOTAL | Withdrawal or refund amount is inconsistent with the amount in order. |
| SELLER_BALANCE_NOT_ENOUGH | The balance of seller is not enough. |
| ACCOUNT_BALANCE_NOT_AVALIABLE_TEMPORILY | The balance of the user’s account is temporally not available. |
| ACCOUNT_NOT_EXISTS | The account is not exist. |
| FOREX_REFUND_CURENCY_NOT_EQUAL_TRADE_CURENCY | The refund pricing currency is different from the transaction pricing currency. |
| FOREX_REFUND_NOT_SET_CURENCY | Refund to foreign currency transaction needs to set refund currency. |
| FOREX_REFUND_RATE_NOT_FOUND | The transaction fx rate cannot be retrieved when refunding. |
| FORIGEN_CURRENCY_DECIMAL_NUM_NOT_EXISTS | Cannot retrieve the currency decimal count for foreign currency transaction |
| FORIGEN_CURRENCY_TOTAL_FEE_NOT_MATCH_DECIMAL_NUM | The input foreign currency amount is not matching the supported format (decimal digit not match) |
| FORIGEN_CURRENCY_TOTAL_FEE_NOT_NULL | The foreign currency amount is not correct |
| MERCHANT_BALANCE_NOT_ENOUGH | Merchant balance is not enough for refund |
| NOT_THIS_PARTNERS_TRADE | The trade is not belonged to the partner |
| REASON_REFUND_AMOUNT_LESS_THAN_COUPON_FEE | Alipay coupon cannot be partially refunded. |
| REASON_TRADE_REFUND_FEE_ERR | Refund fee amount error |
| REFUND_AMOUNT_NOT_VALID | The refund amount is not valid |
| SELLER_ACCOUNT_HAD_FREEZE | The seller account is freeze |
| SELLER_BALANCE_NOT_ENOUGH | The seller account balance is not enough |
| TRADE_PRODUCT_NOT_ALLOW_REFUND | The product is not allow refund |
| TRADE_STATUS_NOT_ALLOW_REFUND | Refund is not allowed for the trade status. |
| UNFOREX_TREADE_NOT_ALLOW_FOREX_FOUND | Domestic transaction cannot accept forex refund |
| BUYER_ENABLE_STATUS_FORBID | Buyer account status prohibits the refund |
Access errors
| Error code | Description |
| ILLEGAL_SIGN | Illegal signature. |
| ILLEGAL_DYN_MD5_KEY | Dynamic key information is incorrect. |
| ILLEGAL_ENCRYPT | Encryption is incorrect. |
| ILLEGAL_ARGUMENT | Parameter is incorrect. |
| ILLEGAL_SERVICE | Service parameter is incorrect. |
| ILLEGAL_USER | User ID is incorrect. |
| ILLEGAL_PARTNER | Partner ID is incorrect. |
| ILLEGAL_EXTERFACE | Interface configuration is incorrect. |
| ILLEGAL_PARTNER_EXTERFACE | Partner’s interface information is incorrect. |
| ILLEGAL_SECURITY_PROFILE | Matching private key configuration has not been found. |
| ILLEGAL_AGENT | Agency ID is incorrect. |
| ILLEGAL_SIGN_TYPE | The signature type is incorrect. |
| ILLEGAL_CHARSET | The character set is illegal. |
| HAS_NO_PRIVILEGE | Has no right to visit. |
| INVALID_CHARACTER_SET | The character set is invalid. |
System errors
| Error code | Description |
| SYSTEM_ERROR | Alipay system error |
| SESSION_TIMEOUT | Session timeout |
| ILLEGAL_TARGET_SERVICE | Wrong target_service |
| ILLEGAL_ACCESS_SWITCH_SYSTEM | Merchant is not allowed to visit system of this type. |
| EXTERFACE_IS_CLOSED | The interface has been closed. |
Refund funding channel
| Code | Payment channel |
| ALIPAYACCOUNT | Alipay Balance |
| COUPON | Alipay Red Envelop |
| POINT | Alipay Points |
| BANKCARD | Bank card |
| DISCOUNT | Alipay Discount |
| FINANCEACCOUNT | Special Alipay account for financial management |
| TMALLFUND | Tmall Fund |
| PCARD | Prepaid card |
| MCARD | Merchant’s card |
| MDISCOUNT | Merchant’s discount coupon |
| MCOUPON | Merchant’s Red Envelope |
Samples
Request sample
https://mapi.alipay.com/gateway.do?operator_id=OP001&sign_type=RSA&out_trade_no=HZ0120131127001&operator_type=1&sign=363a752668ee2b3b8f124c623bd028ad&_input_charset=UTF-8&service=alipay.acquire.refund&out_request_no=HZ01RF001&partner=2088101125328850&refund_reason=%E6%AD%A3%E5%B8%B8%E9%80%80%E6%AC%BE&refund_amount=200&alipay_ca_request=2
Response sample
Business is accepted and processed normally, and refund is conducted successfully:
copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="sign">8c066dc2cb92a9c2c8070d935917fa73</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">RSA</param>
<param name="service">alipay.acquire.refund</param>
<param name="out_request_no">daiqing121</param>
<param name="partner">2088101125936190</param>
<param name="refund_reason">refund on behalf of qing</param>
<param name="refund_amount">1.00</param>
<param name="out_trade_no">6823789339978248</param>
</request>
<response>
<alipay>
<result_code>SUCCESS</result_code>
<buyer_logon_id>159****5620</buyer_logon_id>
<buyer_user_id>2088102122524333</buyer_user_id>
<fund_change>Y</fund_change>
<out_trade_no>6823789339978248</out_trade_no>
<trade_no>2013112011001004330000121536</trade_no>
</alipay>
</response>
<sign>fc209d86b57b2adb23254a897ebaa7d9</sign>
<sign_type>RSA</sign_type>
</alipay>Request succeeds, business processing fails:
copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="sign">8c066dc2cb92a9c2c8070d935917fa73</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">RSA</param>
<param name="service">alipay.acquire.refund</param>
<param name="out_request_no">daiqing121</param>
<param name="partner">2088101125936190</param>
<param name="refund_reason">refund on behalf of Qing</param>
<param name="refund_amount">1.00</param>
<param name="out_trade_no">6823789339978248</param>
</request>
<response>
<alipay>
<result_code>FAIL</result_code>
<detail_error_code>TRADE_STATUS_ERROR</detail_error_code>
<detail_error_des>illegal trade status</detail_error_des>
</alipay>
</response>
<sign>fc209d86b57b2adb23254a897ebaa7d9</sign>
<sign_type>RSA</sign_type>
</alipay>Output when Request fails or the data accessed is wrong:
copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>