void

Overview

POST /v1/payments/void is used to void a paid order before the payment is captured, and then return money to the payer. There are the following two types of voiding a paid order:

• Partially void: To partially void a paid order will return a part of the payment amount to the payer. It will not change the order status. There is a timeout setting for the remaining payment amount. Once the time is out of the setting, the remaining payment amount will be voided or confirmed automatically.
• Fully void: To fully void an order will close the order automatically.

The timeout setting is available when the remaining payment amount is voided or confirmed automatically if the session timeout is set.

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

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 initiate 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 18).
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(Step 19).
20. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
21. If the merchant cannot fulfill the order or needs to void the transaction, the merchant initiates the void process (Step 21).
22. The merchant backend calls the void API to return the money to the customer (Step 23).
23. Send void request via /v1/payments/void.
24. The E-Wallet backend returns the void result to the merchant backend.
25. The merchant backend returns void result.
26. And the Mini Program displays the void result to the user(Step 26).

Alternative flow: When the E-Wallet backend returns the resultCode as VOID_IN_PROCESS, the merchant can call inquiryPayment API to query void result (Step 27).

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

Sample Request

{
  "voidRequestId": "2023010123456789013",
  "paymentId": "202312061112128001016xx",
  "voidAmount": {
    "value": "40000",
    "currency": "IQD"
  }
}

The voidRequestId is used for idempotence—repeat submissions with the same ID will yield the same final result.

Response

Sample Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "voidRequestId": "2023010123456789013",
  "voidId": "202312061112128017xxx"
}

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.

Related Links

• pay (Use product code 51051000101000100008 for escrow)
• merchantAccept
• cancel
• refund
• inquiryPayment