Integrate trade.refund API to Automate Buyer Refunds - Mobile Platform as a Service

When a refund is required after a transaction because of buyer or seller reasons, the seller can use the refund interface to return the payment to the buyer. After receiving and successfully verifying the refund request, the platform returns the payment to the buyer's account through the original payment channel according to the refund rules.

The cumulative refund amount submitted for the same transaction cannot exceed the original total transaction amount.

Common request parameters

Parameter	Type	Required	Maximum length	Description	Example value
app_id	String	Required	32	Mini program ID	2014072300007148
method	String	Required	128	API name	trade.refund
format	String	No	40	Only JSON is supported	JSON
charset	String	Required	10	The encoding format used for the request, such as utf-8, gbk, gb2312, etc.	utf-8
sign_type	String	Required	10	The signature algorithm type used by the merchant to generate the signature string. Currently, RSA2 and RSA are supported. RSA2 is recommended.	RSA2
sign	String	Required	344	The signature string of the merchant request parameters. For more information, see the signature.	See the example in this topic.
timestamp	String	Required	19	The time when the request is sent, in the format `yyyy-MM-dd HH:mm:ss`	2014-07-24 03:07:50
version	String	Required	3	The version of the API being called. Fixed value: 1.0	1.0
biz_content	String	Required	-	A collection of request parameters with no maximum length. All request parameters except common parameters must be passed in this parameter. For more information, see the quick integration documentation for each product.	-

Business request parameters

Parameter	Type	Required	Maximum length	Description	Example value
refund_amount	String	Required	16	Refund amount. The amount to be refunded cannot exceed the order amount. The unit is defined based on business, and two decimal places are supported. Note If marketing is used in a forward transaction, the refund amount includes the marketing amount. The platform will allocate the marketing amount and the buyer's own funds according to the business rules, and the buyer's own funds will be refunded first by default. For example, if the total transaction amount is 100 USD, the user uses 80 USD of own funds and 20 USD of marketing coupons without cash flow when paying, and the merchant actually receives 80 USD. If the first request for a refund of 60 USD is made, the 60 USD will be deducted from the merchant's collection funds and returned to the user's own assets; if a refund of 40 USD is requested, 20 USD will be deducted from the merchant's collection funds and returned to the user's assets, and the 20 USD marketing coupon will be returned to the user (whether the coupon can be reused depends on the coupon rule configuration).	200.12
out_trade_nostring	String	No	64	Merchant order number. The merchant order number passed during order payment, which is customized by the merchant and must be unique in the merchant's system. Cannot be empty at the same time as the platform transaction number trade_no.	20150320010101001
trade_no	String	No	64	Platform transaction number. Cannot be empty at the same time as the merchant order number out_trade_no. When both exist, trade_no takes precedence.	2014112611001004680073956707
refund_reason	String	No	256	Refund reason explanation. Customized by the merchant, it will be displayed in the merchant's and user's PC refund bill details.	Normal refund
out_request_no	String	No	64	Refund request number. Identifies a refund request and must be unique under the transaction number. This parameter is required for partial refunds. Note For the same refund request, if the call interface fails or is abnormal, the refund request number must not be changed when retrying to prevent duplicate refunds of the transaction. The platform will ensure that the same refund request number will only be refunded once for multiple requests. Required for partial refunds	HZ01RF001
buyer_open_id	String	Required	128	Buyer's unique identifier	074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5
body	string	No	128	Additional order information. If this parameter is passed in the request, it will be returned as is in the asynchronous notification and statement, and will also be displayed as a transaction description in the merchant and user's PC bill details.	iPhone6 16G

Common request example

Default example:

curl 'https://xxx/gateway.do?charset=UTF-8&method=trade.refund&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'biz_content={
	"out_trade_no":"20150320010101001",
	"trade_no":"2014112611001004680073956707",
	"refund_amount":"200.12",
	"refund_reason":"Normal refund",
	"out_request_no":"HZ01RF001",

Note

This example is for reference only.

Common response parameters

Parameter	Type	Required	Maximum length	Description	Example value
code	String	Required	-	The code returned by the gateway	40004
msg	String	Required	-	The description of the code returned by the gateway	Business Failed
sub_code	String	No	-	Business return code. See the specific API documentation.	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	No	-	Business return code description. See the specific API documentation.	The transaction has been paid
sign	String	Required	-	Signature	DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

Business response parameters

Parameter	Type	Required	Maximum length	Description	Example value
out_trade_no	String	Required	64	Merchant order number	20150423001001
trade_no	String	Required	64	Payme transaction number	2015042321001004720200028594
buyer_open_id	String	Required	100	Buyer's unique identifier	074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5
refund_fee	String	Required	11	Total refund amount. The unit is defined based on business. Refers to the cumulative amount that has been successfully refunded for this transaction.	88.88

Response example

{
    "trade_refund_response": {
        "code": "10000",
        "msg": "Success",
        "trade_no": "2013112011001004330000121536",
        "out_trade_no": "6823789339978248",
        "refund_fee": "88.88",
        "buyer_open_id": "074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}