/v2/payments/inquiryRefund

2022-11-17 04:34

POST /v2/payments/inquiryRefund

The inquiryRefund API is used to inquire the refund result, usually when merchants are not able to receive the refund result after a long period of time.

Note:

After the merchant initiates refund and not able to receive the refund result after a long period of time, it can poll Refund Inquiry interface of AMS.
The merchant uses InquiryRefund to determine the refund status in the asynchronous refund processing scenario.
Round-robin interval, recommended 5 seconds once, up to 1 minute.

Message structure

Request

Property	Data type	Required	Description	Example
refundId	String	No	The unique ID of a refund generated by Wallets. Max. length: 64 characters.	"1022188000000000001xxxx"
refundRequestId	String	No	The unique ID of a refund generated by Merchants. Max. length: 64 characters.	"20200101234567890132xxxx"
extendInfo	String	No	The extend information, wallets and merchants can put extending information in this property. Max. length: 4096 characters.	"This is additional information"

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information such as status and error codes.	{ "resultCode":"SUCCESS", "resultStatus":"S", "resultMessage":"success" }
refundId	String	No	The unique ID of a refund generated by Wallet. Max. length: 64 characters.	"20200101234567890144444xxxx"
refundRequestId	String	No	The unique ID of a refund generated by Merchant. Max. length: 64 characters.	"20200101234567890155555xxxx"
refundAmount	Amount	No	Refund amount for display of user consumption records page.	{ "value":"100", "currency":"USD" }
refundReason	String	No	Refund reason. Max. length: 256 characters.	"have returned goods to the shop"
refundTime	String/Datetime	No	The point in time when money is successfully deducted from merchants. Then will start to refund money to users. This time format follows the ISO 8601 standard.	"2020-01-02T12:01:01+08:30"
refundStatus	String	No	PROCESSING - refund is processing. SUCCESS - refund succeeds. FAIL - refund fails.	"SUCCESS"
refundFailReason	String	No	The failure reason of a refund order when refundStatus is `FAIL` . Max. length: 256 characters.	"the fail reason of refund order when refundStatus is FAIL."
extendInfo	String	No	The extensive information. Wallets and merchants can put extensive information here. Max. length: 4096 characters.	"This is additional information"

Result Process Logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The corresponding `result.resultCode` is "SUCCESS" and the `result.resultMessage` is "Success". It means that the refund inquiry is successful. And you have to check the `refundStatus` field： if `refundStatus` is PROCESSING, the refund is processing. if `refundStatus` is SUCCESS, the refund succeeds. if `refundStatus` is FAIL, the refund is failed.
A	The corresponding `result.resultCode` is "ACCEPT"; and the `result.resultMessage` varies based on different situations.
U	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. It means that when the refund inquiry request is processed, an unknown exception occurs, which is probably due to system or network issues, the merchant can retry.
F	That means this transaction is failed. The corresponding `result.resultCode` and `result.resultMessage` vary based on different situations. For details, see the following Error codes section. It means that the refund inquiry is failed. When `resultCode` is REFUND_NOT_EXIST, it means that the refund is not yet accepted and can be treated as a refund failure. For the other failure reasons, human intervention is recommended.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	REFUND_NOT_EXIST	Refund is not exist.
F	EXPIRED_AGENT_TOKEN	The agent token of Mini Program is expired.
F	INVALID_AGENT_TOKEN	The agent token of Mini Program is invalid.

Sample

For example, a Korean user purchases a 100 USD merchandise at a Japanese merchant with cross-border payment.

The merchant refunds the money, but not return the refund result, so the merchant begins to inquiry the refund result.

The user could start refund request from the Mini Program or the merchant cashier （Step 1).
The merchant server calls /v2/payments/refund interface to refund (Step 2).
E-wallet returns the refund result to the merchant server (Step 3).
Also the merchant server could call /v2/payments/inquiryRefund interface to query the refund result (Step 4).
E-wallet returns refund inquiry result to the merchant server (Step 5).
The merchant should return the refund result to the Mini Program or the merchant cashier (Step 6).

Request

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

refundId refundId return by wallet.
refundRequestId the uniqueId of a refund generated by Merchant.

Note:

This interface support querying with refundId or refundRequestId. paymentId has a higher priority than refundRequestId, which means that if you offer both refundId and refundRequestId, we will use refundId and ignore refundRequestId.

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==S shows that the refund is successful.
refundId refundId return by wallet.
refundRequestId merchant refund request id.
refundAmount refund amount by merchant.
refundReason describes the refund reason.
refundTime refund process finish time, that means deduct from merchant success.
refundStatus refund Status.

refundStatus.PROCESSING:refund is processing.
refundStatus.SUCCESS:refund success.
refundStatus.FAIL:refund failed.

refundFailReason the fail reason of refund order when refundStatus is Fail.