/v1/payments/inquiryRefund
POST /v1/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 to payer status in the asynchronous refund processing scenario.
- Round-robin interval, recommended 5 seconds once, up to 1 minute.
Note: All monetary values in the fields of request and response in their smallest currency units, and for IQD, the smallest unit is fils. Thus, if a transaction amount is 150 IQD, the value will be gaven as 150000.
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 generated by Wallets. Max. length: 64 characters. | "2023120611121280130016600090000xxxx" |
refundRequestId | String | No | The unique ID of a refund generated by Merchants. Max. length: 64 characters. | "20230101234567890132xxxx" |
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. | "2023120611121280010016600090000xxxx" |
refundRequestId | String | No | The unique ID of a refund generated by Merchant. Max. length: 64 characters. | "20230101234567890155555xxxx" |
refundAmount | Amount | No | Refund amount for display of user consumption records page. | { Â Â "value":"100", Â Â "currency":"IQD" } |
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. | "2023-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." |
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Â
|
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. |
Sample
For example, a Korean user purchases a 100 IQD 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 Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
- The E-wallet App service calls authorization service to processes the authorization information.
- The E-wallet backend verifies the authorization information, generates the authCode and returns.
- The E-wallet App service returns the authCode to the Mini Program.
- The Mini Program sends the authCode to the merchant backend.
- The merchant backend calls the applyToken API with authCode to apply the accessToken.
- The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
- The Mini Program creates an order with customerId.
- The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
- The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
- The merchant backend passes the payment detail information to the Mini Program.
- The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
- The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
- The user confirms the payment in the cashier page.
- The E-Wallet App Service calls payment service and execute the payment process.
- When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
- Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
- Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
- After the service or goods has been delivered, the user could start a fully refund or partial refund in the Mini Program or the merchant cashier (Step 21).
- The Mini Program sends the refund request to merchant backend, and the merchant backend calls the refund API to refund the money(Step 23).
- The E-Wallet backend returns the refund result to the merchant backend.
- And the Mini Program displays the refund result to the user(Step 26).
- When the E-Wallet backend returns the resultCode as REFUND_IN_PROCESS, the merchant can call
inquiryRefund
API to query refund result (Step 27).
Request         Â
{
"refundId": "2023120611121280130016600090000xxxx",
"refundRequestId":"20230101234567890132xxxx"
}
- refundId refundId return by wallet.
- refundRequestId the uniqueId of a refund generated by Merchant.
Note:
This interface support querying with refundId or refundRequestId. refundId 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":"2023120611121280130016600090000xxxx",
"refundRequestId": "20230101234567890155555xxxx",
"refundAmount":{
"value":"100",
"currency":"IQD"
},
"refundReason":"refund reason.",
"refundTime":"2023-01-02T12:01:01+08:30",
"refundStatus":"FAIL",
"refundFailReason":"the fail reason of refund order when refundStatus is FAIL."
}
- 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.