/v2/payments/inquiryRefund
POST /v2/payments/inquiryRefund
The inquiryRefund
 API is used to inquire about 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 a refund and does not receive the refund result after a long period of time, it can poll the 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
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:
Request
Property | Data type | Required | Description | Example |
refundId | String | No | The unique ID of a refund is generated by the wallet. 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 extended information that wallets and merchants want to describe. Max. length: 4096 characters. | copy
|
Response
Property | Data type | Required | Description | Example |
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 is generated by the wallet. Max. length: 64 characters. | "20200101234567890144444xxxx" |
refundRequestId | String | No | The unique ID of a refund is generated by the merchant. Max. length: 64 characters. | "20200101234567890155555xxxx" |
refundAmount | No | Order amount on the refund results page, which displays user consumption records. | { Â Â "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 |
| "SUCCESS" |
refundFailReason | String | No | The failure reason of a refund order when refundStatus is
Max. length: 256 characters. | "the fail reason of refund order when refundStatus is FAIL." |
extendInfo | String | No | The extended information that the wallet and merchants want to describe. Max. length: 4096 characters. | copy
|
Result Process Logic
In the response, the result.resultStatus
field indicates the result of processing a request as follows.
resultStatus | Description |
S | The corresponding It means that the refund inquiry is successful. And you have to check theÂ
|
U | The corresponding 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 It means that the refund inquiry is failed. When |
Error codes
Error codes are usually classified into the following categories:
- Common error codes are common for all mini program's OpenAPIs. Â
- API-specific error codes are listed in the following table.
resultStatus | resultCode | resultMessage | Further Action |
F | REFUND_NOT_EXIST | Refund is not exist. | |
F | EXPIRED_AGENT_TOKEN | The agent token of a mini program is expired. | |
F | INVALID_AGENT_TOKEN | The agent token of a mini program is invalid. |
Sample
For example, a Korean user purchases 100 USD merchandise at a Japanese merchant with cross-border payment.
The merchant refunds the money but does not return the refund result, so the merchant begins to inquiry about the refund result. Â Â Â
- The user could start a refund request from the mini program or the merchant cashier (Step 1).
- The merchant server calls /v2/payments/refund interface to refund (Step 2).
- The 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).
- The wallet returns the 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         Â
{
"refundId": "1022188000000000001xxxx",
"refundRequestId":"20200101234567890132xxxx"
}
- refundId is returned by the wallet.
- refundRequestId is the unique ID of a refund generated by the 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
{
"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 is returned by the wallet.
- refundRequestId means that merchant refund request ID.
- refundAmount describes the refund amount by the merchant.
- refundReason describes the refund reason.
- refundTime describes the refund process finish time, which means to deduct from merchant success.
- refundStatus describes refund statuses.
- refundStatus.PROCESSING means that a refund is processing.
- refundStatus.SUCCESS means a refund is successful.
- refundStatus.FAIL means that a refund is failed.
- refundFailReason describes the fail reason of refund order when refundStatus is Fail.