/v2/payments/inquiryRefund
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 | 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 |
| "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 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 It means that the refund inquiry is successful. And you have to check theÂ
|
A | The corresponding |
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 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         Â
{
"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
{
"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.