/v1/payments/inquiryRefund
POST /v1/payments/inquiryRefund
The inquiryRefund
 API is used to inquire the refund result, usually when not able to receive the refund result after a long period of time. Such as:
Note:
- After 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.
- Merchant uses InquiryRefund to determine the Refund status in the asynchronous Refund processing scenario.
- Round-robin interval, recommended 5s once, up to 1 minute.
Message structure
Request
Property | Data type | Required | Description |
partnerId | String | Yes | The partnerId allocated by wallet. Max. length: 32 characters. |
refundId | String | No | The unique ID of a refund generated by Wallet. Max. length: 64 characters. |
refundRequestId | String | No | The unique ID of a refund generated by Merchant. Max. length: 64 characters. |
extendInfo | String | No | The extend information,wallet and merchant can put extend info here. Max. length: 4096 characters. |
Response
Property | Data type | Required | Description |
result | Yes | The request result, which contains information related to the request result, such as status and error codes. | |
refundId | String | No | The unique ID of a refund generated by Wallet. Max. length: 64 characters. |
refundRequestId | String | No | The unique ID of a refund generated by Merchant. Max. length: 64 characters. |
refundAmount | Amount | No | Refund amount for display of user consumption records page. |
refundReason | String | No | Refund reason. Max. length: 256 characters. |
refundTime | String/Datetime | No | Deduct money from merchant success time, after then will start to refund money to user. which follows the ISO 8601 standard. |
refundStatus | String | No | PROCESSING - refund is processing. SUCCESS - refund success. FAIL - refund failed. |
refundFailReason | String | No | The fail reason of refund order when refundStatus is FAIL. Max. length: 256 characters. |
extendInfo | String | No | The extend information,wallet and merchant can put extend info here. Max. length: 4096 characters. |
Result Process Logic
For different request results, different actions are to be performed. See the following list for details:
- If the value of result.resultStatus is S, the refund inquiry is successful. And you have to check refundStatus:
- Â if refundStatus is PROCESSING, means refund is processing;
- if refundStatus is SUCCESS, means refund success;
- if refundStatus is FAIL, means refund failed.
- If the value of result.resultStatus is F, the refund inquiry is fail. When resultCode is REFUND_NOT_EXIST, it means that the refund is not yet accepted and can be treated as refund failure. For the other failure reason, human intervention is recommended.
- If the value of result.resultStatus is U, the refund inquiry is unknown exception.processing failure occurs, probably due to system / network issues, Â merchant can retry.
Result
No | resultStatus | resultCode | resultMessage |
1 | S | SUCCESS | Success. |
2 | U | UNKNOWN_EXCEPTION | An API calling is failed, which is caused by unknown reasons. |
3 | U | REQUEST_TRAFFIC_EXCEED_LIMIT | The request traffic exceeds the limit. |
4 | F | REFUND_NOT_EXIST | Refund is not exist. |
5 | F | INVALID_API | The called API is invalid or not active. |
6 | F | PARAM_ILLEGAL | Illegal parameters. For example, non-numeric input, invalid date. |
7 | F | PROCESS_FAIL | A general business failure occurred. Don't retry. |
8 | F | ACCESS_DENIED | The access is denied. |
9 | F | EXPIRED_AGENT_TOKEN | The access token of mini program is expired. |
10 | F | INVALID_AGENT_TOKEN | The access 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.
Merchant refund the money, but not return the refund result. so merchant begin to inquiry refund result. Â Â Â
- User could start refund request from the Mini Program or the merchant cashier (Step 1).
- The merchant server calls /v1/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 /v1/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",
"partnerId":"1022172000000000001xxxx",
"extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
}
- refundId refundId return by wallet.
- refundRequestId the uniqueId of a refund generated by Merchant.
- partnerId the partnerId allocated by wallet.
- extendInfo, includes key - customerBelongsTo the e-wallet that the customer uses. Corresponding to the field 'siteName' that obtained from the API 'my.getSiteInfo'.
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":"MYR"
},
"refundReason":"refund reason.",
"refundTime":"2020-01-02T12:01:01+08:00",
"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.