Official Account ID

appid

String(32)

Yes

Specifies an Official Account ID assigned by WeChat
Example: wx8888888888888888

Merchant ID

mch_id

String(32)

Yes

Specifies merchant ID assigned by WeChat Payment
Example: 1900000109

Sub Official Account ID

sub_appid

String(32)

No

Specifies an Sub Official Account ID assigned by WeChat
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: wx8888888888888888

Sub  Merchant ID

sub_mch_id

String(32)

Yes

Specifies Sub merchant ID assigned by WeChat Payment
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109

Random string

nonce_str

String(32)

Yes

32 characters or fewer. For more information, see Random String Algorithm .
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS

Signature

sign

String(64)

Yes

Specifies a signature. For more information, see Signature Algorithm.
Example: C380BEC2BFD727A4B6845133519F3AD6

Sign type

sign_type

String(32)

No

Currently HMAC-SHA256 and MD5 are supported, default is MD5. This parameter must be submitted if HMAC-SHA256 is chosen
Example: HMAC-SHA256/MD5

WeChat Order Number

transaction_id

String(32)

Choose one to submit

Specifies the WeChat payment order id number.

Example: 1217752501201407033233368018

Merchant Order Number

out_trade_no

String(32)

out_trade_no is an internal order number within the merchant’s system.
transaction_id will be used over out_trade_no if they are both provided by the merchant.
Example: 1217752501201407033233368018

Merchant Refund Number

out_refund_no

String(32)

Yes

Specifies the internal refund number, which is unique in the system. A single transaction can be processed as multiple partial refunds, with the total sum of the partial refunds being equal to the original one.
Example: 1217752501201407033233368018

Total Amount

total_fee

int

Yes

Specifies the total order amount. The units are expressed in cents and must be an integer. For more information, see Payment Amount.
Example: 100

Refund Amount

refund_fee

int

Yes

Specifies the total refund amount for a transaction. The units are expressed in cents and shall be an integer.

Currency Type

refund_fee_type

String(8)

No

ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Currency Type.
Example: USD

Refund Reason

refund_desc

String(80)

No

It will inform the shoppers the refund reason once merchants submit this field value.
Example: Products sold out

Return Status Code

return_code

String(16)

Yes

Set to SUCCESS or FAIL
Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field.
Example：SUCCESS

Return Data

return_msg

String(128)

No

If not empty, this is the error description. If not empty, this is the error description
Signature Failure
Parameter format checking error
Example：Signature Failure

Result Code

result_code

String(16)

Yes

SUCCESS/FAIL

1.SUCCESS: Receives refund application successfully. To get refund status, calling Query Refund API is required.

2.FAIL: Submitting refund application failed.

Example: SUCCESS

Error Code

err_code

String(32)

No

For more information, please refer to error code list.
Example: SYSTEMERROR

Error Code Description

err_code_des

String(32)

No

Describes result data.
Example: System timed out

Official Account ID

appid

String(32)

Yes

The Official Account ID submitted when calling the interface
Example: wx8888888888888888

Merchant ID

mch_id

String(32)

Yes

The Merchant ID submitted when calling the interface
Example: 1900000109

Sub Official Account ID

sub_appid

String(32)

No

The Sub Official Account ID submitted when calling the interface
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: wx8888888888888888

Sub  Merchant ID

sub_mch_id

String(32)

Yes

The Sub Merchant ID submitted when calling the interface
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109

Random String

nonce_str

String(32)

Yes

32 characters or fewer
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS

Signature

sign

String(64)

Yes

Specifies a signature. For more information, see Signature Algorithm
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS

WeChat Order Number

transaction_id

String(32)

Yes

Specifies the WeChat payment order id
Example：1217752501201407033233368018

Merchant Order Number

out_trade_no

String(32)

Yes

Specifies the order number created within the Merchants' system, which is consistent with request.
Example：1217752501201407033233368018

Merchant Refund Number

out_refund_no

String(32)

Yes

Merchant Refund Number.
Example: 1217752501201407033233368018

WeChat Refund Number

refund_id

String(32)

Yes

WeChat Refund Number.
Example: 1217752501201407033233368018

Refund Amount

refund_fee

int

Yes

Specifies the total refund amount expressed in cents and must be an integer.
Example: 100

Currency Type

refund_fee_type

String(8)

Yes

ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Section 4.2 Currency Type.
Example: USD

Total Amount

total_fee

int

Yes

Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Payment Amount.
Example：100

Order Currency Type

fee_type

String(8)

No

ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type.
Example: CNY

Cash Payment Amount

cash_fee

int

Yes

Specifies the cash payment amount expressed in cents and must be an integer. For more information, see Payment Amount.
Example: 100

Currency Type

cash_fee_type

String(8)

Yes

Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Section 4.2 Currency Type.
Example: CNY

Cash Refund Amount

cash_refund_fee

int

Yes

Specifies the cash refund amount expressed in cents and must be an integer. For more information, see Payment Amount.
Example: 100

Cash Refund Currency Type

cash_refund_fee_type

String(8)

No

Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Currency Type.
Example: CNY

SYSTEMERROR

API return error

System timed out

Call this API again using the same parameters

BIZERR_NEED_RETRY

internal error

internal error caused by concurrency

Please retry with the same parameter and do not change the out_refund_no

TRADE_OVERDUE

Beyond refund period

The longest refund period of one order is 365 days

Please find another way to refund

ERROR

Business error

Business error when initiate refund

The detailed reason will return

USER_ACCOUNT_ABNORMAL

Refund request failed

User’s account cancelled

This error code means refund request failed, merchants need to handle the refund by themselves

INVALID_REQ_TOO_MUCH

Invalid request count reaches the limit

There are too much invalid requests

Please check whether your system is working well

NOTENOUGH

Not enough unsettled fund for refund

There is not enough unsettled fund for refund

This error code means refund request failed, merchants need to recall the refund API once there is enough unsettled fund, or retry it continuously

INVALID_TRANSACTIONID

Invalid transaction_id

Requested parameters are not correct

Incorrect request parameters. Check whether the original transaction ID exists or whether data failed to be returned from the payment interface.

PARAM_ERROR

Parameter error

Requested parameters are not correct

Incorrect request parameters. Check the parameters and call the Submit Refund API again.

APPID_NOT_EXIST

APPID DOES NOT EXIST

No APPID in this parameter

Check whether the provided APPID is correct

MCHID_NOT_EXIST

MCHID DOES NOT EXIST

No MCHID in this parameter

Check whether the provided MCHID is correct

APPID_MCHID_NOT_MATCH

appid does not match mch_id

appid does not match mch_id

Check whether appid belongs to the associated mch_id

REQUIRE_POST_METHOD

Use post method

Data is not transferred by post

Check whether data is submitted by POST method

SIGNERROR

Signature error

Incorrect signature result

Check whether the signature parameter and method complies with signature algorithm requirements

XML_FORMAT_ERROR

INVALID XML FORMAT

INVALID XML FORMAT

Check whether XML parameters are in the correct format