Super Qi LogoMiniapps Docs
Payments

refund

Initiate wallet refunds for previously completed payments.

Overview

POST /v1/payments/refund deducts funds from the merchant and returns them to the user for a successful payment. Partial or full refunds are supported, and multiple refund requests can be made against a single payment as long as the cumulative amount does not exceed the original payment value.

All monetary amounts must be provided in the smallest currency unit (IQD fils). For example, 100 IQD equals 100000.

  • Submit refunds after confirming the underlying payment reached a final success state.
  • Poll /v1/payments/inquiryRefund if the refund status remains REFUND_IN_PROCESS after submission.
  • For escrow payments: Use cancelPayment before merchant accepts, or voidPayment after acceptance. Use refund only after order completion or void.

  1. Mini Program obtains authorization via my.getAuthCode.
  2. Wallet app service validates the authorization with the wallet backend.
  3. Wallet backend issues an authCode.
  4. Wallet app service returns the authCode to the Mini Program.
  5. Mini Program forwards the authCode to the merchant backend.
  6. Merchant backend exchanges the authCode for tokens using applyToken.
  7. Wallet backend returns token information (accessToken, refreshToken, customerId) to the merchant backend.
  8. Mini Program creates the original payment order with customerId.
  9. Merchant backend initiates payment via /v1/payments/pay.
  10. Wallet backend responds with cashier details (including redirectionUrl).
  11. Merchant backend sends payment details to the Mini Program.
  12. Mini Program calls my.tradePay to launch the cashier.
  13. Wallet app service displays the cashier UI with order info.
  14. Wallet app service shows the order page to the user.
  15. User confirms the payment.
  16. Wallet app service executes the payment.
  17. Wallet backend processes the payment and returns the result to the wallet app service.
  18. Mini Program receives the payment result.
  19. Wallet backend notifies the merchant backend via paymentNotifyUrl.
  20. Wallet backend notifies the user via SMS/email/inbox.
  21. User or merchant initiates a full or partial refund request.
  22. Mini Program submits the refund request to the merchant backend.
  23. Merchant backend calls /v1/payments/refund.
  24. Wallet backend returns the refund result to the merchant backend.
  25. Wallet backend returns the refund result to the Mini Program.
  26. Mini Program displays the refund status to the user.
  27. If refund status is REFUND_IN_PROCESS, merchant backend polls /v1/payments/inquiryRefund.
  28. Wallet backend responds with the latest refund inquiry result.

Endpoint

MethodPath
POST/v1/payments/refund

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

FieldTypeRequiredDescriptionExample
refundRequestIdstringYesMerchant-generated refund ID (max 64 characters). Used for idempotence—repeat submissions with the same ID yield the same final result."202311271907410100070000008881xxxx"
paymentIdstringConditionalWallet payment ID associated with the refund. Provide either paymentId, paymentRequestId, or captureId."202312061112128001001660090000xxxx"
paymentRequestIdstringConditionalMerchant payment ID associated with the refund."20230101234567890133333xxxx"
captureIdstringConditionalWallet capture ID (used in capture flows)."202311271907410100070000007777xxxx"
refundAmountobjectYesRefund amount object. value must not exceed the remaining refundable amount.{ "currency": "IQD", "value": "100000" }
refundReasonstringNoDescription of why the refund is issued (max 256 characters)."Returned goods to merchant"
extendInfostringNoAdditional metadata in JSON format (max 2048 characters)."extendInfo": "additional information"
{
  "refundRequestId": "202311271907410100070000008881xxxx",
  "paymentId": "202312061112128001001660090000xxxx",
  "refundAmount": {
    "currency": "IQD",
    "value": "100000"
  },
  "refundReason": "Customer requested cancellation."
}

At least one of paymentId, paymentRequestId, or captureId must be provided. If multiple are supplied, the wallet prioritizes paymentId, then paymentRequestId, then captureId.

Response

FieldTypeRequiredDescriptionExample
resultobjectYesOutcome metadata including resultCode, resultStatus, and resultMessage.{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "Success." }
refundIdstringConditionalWallet-generated refund ID. Present when resultStatus is S."202312061112128013001660090000xxxx"
refundTimestringConditionalISO 8601 timestamp indicating when funds were deducted from the merchant (returned when resultStatus is S)."2023-11-27T12:01:01+08:30"
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "refundId": "202312061112128013001660090000xxxx",
  "refundTime": "2023-11-27T12:01:01+08:30"
}

Result Processing Logic

StatusDescription
SRefund succeeded—funds deducted from merchant; await user settlement.
URefund request encountered an unknown exception. Do not retry immediately; use /v1/payments/inquiryRefund to check status.
FRefund failed. Review resultCode and resultMessage; see Error codes. Common reasons include exceeding refund window or amount.

Error Codes

resultStatusresultCoderesultMessageRecommended Action
UREFUND_IN_PROCESSRefund is under processing.Poll /v1/payments/inquiryRefund.
FMULTI_REFUND_NOT_ALLOWEDMultiple refund not allowed in agreement.Verify agreement rules; issue a single refund.
FREFUND_NOT_ALLOWEDRefund not allowed in agreement.Check agreement configuration.
FREPEAT_REQ_INCONSISTENTData inconsistent with prior request.Ensure idempotent parameters match original submission.
FPARTNER_STATUS_ABNORMALMerchant status abnormal.Resolve merchant account issues before retrying.
FORDER_NOT_EXISTThe order does not exist.Confirm payment identifiers.
FORDER_STATUS_INVALIDOrder has invalid status (e.g., closed).Verify payment lifecycle.
FREFUND_WINDOW_EXCEEDExceeded allowable refund window.Decline refund or seek manual intervention.
FREFUND_AMOUNT_EXCEEDRequested refund exceeds payment amount.Adjust to remaining refundable amount.
FPARTNER_BALANCE_NOT_ENOUGHMerchant balance insufficient.Top up merchant account before retrying.
FCURRENCY_NOT_SUPPORTCurrency not supported.Use supported currency (e.g., IQD).
FUSER_NOT_EXISTUser identifier invalid.Verify user account.
FUSER_STATUS_ABNORMALUser account status abnormal.Resolve user status before retrying.

Related Links

pay

Create wallet payment orders for cashier and agreement scenarios.

merchantAccept

Merchant accepts an escrow payment to begin order fulfillment.