/v2/payments/inquiryRefund

2023-05-31 12:13

POST /v2/payments/inquiryRefund

With this API call, the merchant can inquire about the status of a refund.

Note: Use refundId or refundRequestId in this API call to inquire about the refund result. refundId has a higher priority than refundRequestId, which means that if you offer both refundId and refundRequestId, we will use refundId and ignore refundRequestId.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request header

Field	Data type	Required	Description	Example
Agent-Token	String	No	An agent token that is issued by the merchant to authorize its ISV for API calls. Specify this parameter if an ISV calls the API in behalf of a merchant.

Request parameters

Field	Data type	Required	Description	Example
refundId	String	No	Indicates the unique ID assigned by the super app to identify a refund. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be `Null`. Note: This field is required when the value of refundRequestId is `Null`.	"1022188000000000001xxxx"
refundRequestId	String	No	Indicates the unique ID assigned by the merchant to identify a refund request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be `Null`. Note: This field is required when the value of refundId is `Null`.	"20200101234567890132xxxx"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Response parameters

AMS多的参数见：https://global.alipay.com/docs/ac/ams/ir_online

Field	Data type	Required	Description	Example
result	Result	Yes	Indicates whether this API call is successful. This field does not indicate the refund result.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
refundId	String	No	Indicates the unique ID assigned by the super app to identify a refund. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"20200101234567890144444xxxx"
refundRequestId	String	No	Indicates the unique ID assigned by the merchant to identify a refund request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"20200101234567890155555xxxx"
refundAmount	Amount	No	Indicates the refund amount. The total refund amount cannot be greater than the total payment amount whether for a partial refund or full refund. Note: This field is returned when this API call is successful (the value of result.resultStatus is `S`).	{ "value": "100", "currency": "USD" }
refundReason	String	No	Indicates the refund reason Maximum length: 256 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	"have returned goods to the shop"
refundTime	Datetime	No	Indicates the actual date and time when a refund is successful. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30". Note: This field is returned when the refund is successful (the value of result.resultStatus is `S`).	"2020-01-02T12:01:01+08:30"
refundStatus	String	No	Indicates the status of a refund. Valid values are: `PROCESSING`: The refund is in progress. `SUCCESS`: The refund is successful. `FAIL`: The refund is failed. Note: This field is returned when there is a refund initiated.	"SUCCESS"
refundFailReason	String	No	The reason for failure Maximum length: 256 characters. Characters not allowed: special characters such as @ # ? Can be `Null` Note: This field is returned when the value of refundStatus is `FAIl`.	"the fail reason of refund order when refundStatus is FAIL."
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	The inquiry is successful. The corresponding result.resultCode is `SUCCESS` and result.resultMessage is `SUCCESS`.
U	The status of the inquiry is unknown. It means that an unknown exception occurs on the super app side. The merchant can try again. The corresponding result.resultCode is `UNKNOWN_EXCEPTION` and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The inquiry is failed, which means this transaction is failed. The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for all mini program's OpenAPIs in V2.
API-specific error codes are listed in the following table.

Error code	Result status	Error message	Further action
REFUND_NOT_EXIST	F	The refund does not exist.	Use a valid refundId or refundRequestId.

Samples

The data flow to inquire about the refund result is illustrated as below:

The merchant server calls this API to inquire about the refund result.
The super app server returns the refund result to the merchant server.

Request

copy
{
        "refundId": "1022188000000000001xxxx",
        "refundRequestId":"20200101234567890132xxxx"
}

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "refundId":"20200101234567890144444xxxx",
 "refundRequestId": "20200101234567890155555xxxx",
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 },
 "refundReason":"refund reason.",
 "refundTime":"2020-01-02T12:01:01+08:30",
 "refundStatus":"SUCCESS",
 "refundFailReason":"the fail reason of refund order when refundStatus is FAIL.",
 "extendInfo":""
}

result.resultStatus is S, which shows that the inquiry is successful.
The refund is successful at refundTime (2020-01-02T12:01:01+08:30).
The total refund amount is 1 USD.