POST /v1/payments/freeze

The freeze API is used to freeze a transaction. Once a transaction has been frozen, it's status shall remain unchanged from the state at the time of freezing. No operations may be performed on a frozen transaction, except for the unfreeze action.

Note:

• Freeze can only be used for escrow pay transactions.
• A transaction can be frozen when the status is AUTH_SUCCESS/MERCHANT_ACCEPT only.
• A frozen transaction cannot be frozen again.
• A transaction can be frozen/unfrozen multiple times.
• If an order is frozen 2 days prior to auto-confirmation, the countdown pauses and locks at 2 days after a successful freeze API call. Once the unfreeze API is successfully called, the system resumes the remaining 2-day countdown.

Message structure

A message consists of a header and body. The following sections focus on the body structure. For the header structure, see：

• Request header
• Response header

Request

Response

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Error codes

Error codes are usually classified into the following categories:

• Common error codes are common across all mini program's APIs.  
• API-specific error codes: are listed in the following table.

Samples

For example, a customer pays 1,000 IQD for a meal on a food delivery platform. After the order is delivered and the customer verifies that the items are incorrect or in bad condition (e.g., incorrect quantity, unacceptable quality, spillage), the customers submit requests to the platform. The platform operator can freeze this transaction.

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 merchant backend returns customerId to mini program.
9. The Mini Program creates an order with customerId.
10. The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
11. The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
12. The merchant backend passes the payment detail information to the Mini Program.
13. The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
14. The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
15. The user confirms the payment in the cashier page.
16. The E-Wallet App Service calls payment service and execute the payment process.
17. When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 19).
18. The E-Wallet App Service returns the payment result to mini program.
19. Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10.
20. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message.
21. The Merchant operator sends the freeze request to merchant backend, and the merchant backend calls the freeze API to freeze the transaction(Step 22).
22. The E-Wallet backend returns the freeze result to the merchant backend(Step 23).
23. And the merchant backend displays the freeze result to the merchant operator(Step 24).
24. When the E-Wallet backend returns the resultStatus as U, the merchant can call inquiryPayment API to query freeze result (Step 25).

Request

{
    "freezeReason":"dispute",
    "requestId":"svVsAfGUrytgAbYiENGeSoNTpdYPHmHO",
    "paymentId":"20260402111212800100166343100072401",
    "freezeOperator":"admin"
}

• paymentId is the unique Id of a payment generated by Wallet, which is the unique payment identifier associated with this freeze.

Response

{
    "result":{
        "resultStatus":"S",
        "resultCode":"SUCCESS",
        "resultMessage":"Success."
    },
    "paymentId":"20260402111212800100166343100072401",
    "requestId":"svVsAfGUrytgAbYiENGeSoNTpdYPHmHO",
    "freezeId":"20260402111212800500166344800000001"
}

• result.resultStatus==S shows that the Wallet freeze is successful.
• freezeId is the unique Id of a freeze generated by Wallet.