inquiryRefund

Overview

POST /v1/payments/inquiryRefund retrieves the current status of a wallet refund. Use this endpoint when the refund completion callback takes longer than expected. All monetary amounts must be sent in the smallest currency unit (IQD fils).

1. Mini Program calls my.getAuthCode with USER_ID scope to request authorization.
2. Wallet app service calls the authorization service to validate the request.
3. Wallet backend returns authCode to the wallet app service.
4. Wallet app service returns authCode to the Mini Program.
5. Mini Program sends the authCode to the merchant backend.
6. Merchant backend invokes applyToken with the authCode to obtain tokens.
7. Wallet backend returns token data (accessToken, refreshToken, customerId) to the merchant backend.
8. Mini Program creates an order using customerId.
9. Merchant backend initiates the payment request with /v1/payments/pay, providing customerId, paymentNotifyUrl, etc.
10. Wallet backend returns payment details (including redirectionUrl) to the merchant backend.
11. Merchant backend forwards the payment details to the Mini Program.
12. Mini Program calls my.tradePay with the redirectionUrl.
13. Wallet app service opens the cashier page with order information.
14. Wallet app service displays the cashier UI to the user.
15. User confirms payment within the cashier UI.
16. Wallet app service triggers the payment execution in the backend.
17. Wallet backend processes the payment and returns the result to the wallet app service.
18. Mini Program receives the payment result from the wallet backend.
19. Wallet backend sends payment notifications to the merchant backend via paymentNotifyUrl.
20. Wallet backend notifies the user via SMS/email/inbox of the payment outcome.
21. User initiates a full or partial refund after receiving goods/services.
22. Mini Program submits the refund request to the merchant backend.
23. Merchant backend calls /v1/payments/refund to request the refund from the wallet backend.
24. Wallet backend returns the refund processing result to the merchant backend.
25. Wallet backend returns refund status to the Mini Program (displayed to user).
26. Mini Program shows the refund result in the UI.
27. If resultCode of the refund is REFUND_IN_PROCESS, merchant backend polls /v1/payments/inquiryRefund using refundId or refundRequestId.
28. Wallet backend responds with the latest refund inquiry result to the merchant backend.

Endpoint

API Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see: OpenAPIs Overview.

Request

{
  "refundId": "202312061112128013001660090000xxxx",
  "refundRequestId": "2023010123456789013255xxxx"
}

If both identifiers are supplied, refundId takes precedence and refundRequestId is ignored.

Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "refundId": "202312061112128013001660090000xxxx",
  "refundRequestId": "2023010123456789013255xxxx",
  "refundAmount": {
    "value": "100000",
    "currency": "IQD"
  },
  "refundReason": "Order cancelled by user.",
  "refundTime": "2023-01-02T12:01:01+08:30",
  "refundStatus": "SUCCESS"
}

Result Processing Logic

Error Codes

Related Links

• my.getAuthCode
• tradePay
• applyToken
• inquiryPayment