cancel

Overview

POST /v1/payments/cancel is used to cancel a payment when the payment result has not been returned for an extended period, or when the merchant, after reviewing the customer's order, decides not to accept it. Upon successful invocation of the cancel API, the full amount paid by the customer will be returned.

To cancel a payment, you need to provide one of the following parameters:

• paymentId: The original payment ID of the payment request to be canceled. It is generated by Alipay when a merchant initiates the original payment.
• paymentRequestId: The original paymentRequestId of the payment request to be canceled.

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 scopes=USER_ID.
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 19).
18. The E-Wallet App Service returns the payment result to mini program.
19. Send cancel request within T day via /v1/payments/cancel.
20. The E-Wallet backend returns cancel 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

Sample Request

{
  "paymentId": "202312061112128001001660090000xxxx"
}

Response

Sample Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "paymentId": "202312061112128001001660090000xxxx",
  "paymentRequestId": "20231127190741010007000070000xxxx",
  "cancelTime": "2023-01-08T12:12:12+08:00"
}

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

The merchant can call this cancel API to cancel the payment transaction within T day under these circumstances and E-Wallet will not settle payment this transaction in T+N day either.

• when the merchant decides to provide a full refund before settlement.
• when the payment result does not return for a long time.
• when the merchant cannot fulfill the order before accepting it.

For refunds after the money has been settled to the merchant, the merchant backend should call refund API instead.

Related Links

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