/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"

refundRequestIdString 

No

The unique ID of a refund generated by Merchants.

Max. length: 64 characters.

"20230101234567890132xxxx"

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.

"2023120611121280010016600090000xxxx"

refundRequestIdString 

No

The unique ID of a refund generated by Merchant.

Max. length: 64 characters.

"20230101234567890155555xxxx"

refundAmountAmount

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"

refundStatusString

No

  • PROCESSING - refund is processing.
  • SUCCESS - refund succeeds.
  • FAIL - refund fails.

"SUCCESS"

refundFailReasonString 

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."

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.

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.
resultStatusresultCoderesultMessage
FREFUND_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.      

refund.png

  1. The Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
  2. The E-wallet App service calls authorization service to processes the authorization information.
  3. The E-wallet backend verifies the authorization information, generates the authCode and returns.
  4. The E-wallet App service returns the authCode to the Mini Program.
  5. The Mini Program sends the authCode to the merchant backend.
  6. The merchant backend calls the applyToken API with authCode to apply the accessToken.
  7. The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
  8. The Mini Program creates an order with customerId.
  9. The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
  10. The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
  11. The merchant backend passes the payment detail information to the Mini Program.
  12. The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
  13. The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
  14. The user confirms the payment in the cashier page.
  15. The E-Wallet App Service calls payment service and execute the payment process.
  16. When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
  17. Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
  18. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
  19. 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).
  20. The Mini Program sends the refund request to merchant backend, and the merchant backend calls the refund API to refund the money(Step 23).
  21. The E-Wallet backend returns the refund result to the merchant backend.
  22. And the Mini Program displays the refund result to the user(Step 26).
  23. 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                  

copy
{
 "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

copy
{
 "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.