/v2/payments/cancel

POST /v2/payments/cancel

The cancel API is used to cancel a payment when the payment result does not return for a long time. You can also use the API to cancel a payment authorization after the authorization is completed.

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 when a merchant initiates the original payment.
  • paymentRequestId: The original paymentRequestId of the payment request to be canceled.

Message structure

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

Request

Property

Data Type

Required

Description

Example

paymentId

String

No

The unique ID that is assigned by the wallet to identify a payment. paymentId and

paymentRequestId cannot both be Null. paymentId and paymentRequestId exists one-to-one correspondence.

Max. length: 64 characters.

20190612184010800100188820200355884

paymentRequestId

String

No

The unique ID is assigned by a merchant to identify a payment request.

paymentRequestId and

paymentId cannot both be

Null. Special characters are not supported. When

paymentRequestId and

paymentId are provided at the same time, paymentId takes precedence.

Max. length: 64 characters.

pay_2089760038715669_202775745075669

extendInfo

String

No

The extended information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Response

Property

Data Type

Required

Description

Example

result

Result

Yes

The request result, which contains information such as result status and error codes.

copy
{
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
}

paymentId

String

No

The unique ID is assigned by the wallet to identify a payment.

Max. length: 64 characters.

20190612184010800100188820200355884

paymentRequestId

String

No

The unique ID is assigned by a merchant to identify a payment request.

Max. length: 64 characters.

pay_2089760038715669_202775745075669

cancelTime

Datetime

No

The actual time when the payment cancellation process is completed. This property is returned only when the cancellation succeeds. The value follows the ISO 8601 standard.

2019-06-12T14:11:35+08:00

extendInfo

String

No

The extended information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Result process logic

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

resultStatus

Description 

S

The cancellation is successful.

The corresponding result.resultCodeis & SUCCESS; and the 

result.resultMessage is Success;.

U

The status of the cancellation result is unknown. 

The corresponding result.resultCode is UNKNOWN_EXCEPTION, and 

result.resultMessage  is "An API calling is failed, which is caused by unknown reasons". For details, see the Common error codes section.

F

The cancellation fails. The corresponding result.resultCode  and

result.resultMessage may vary based on different situations. For details, see the Error codes section.

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.

resultCode

resultStatus

resultMessage

SUCCESS

S

Success

CANCEL_WINDOW_EXCEED

F

The cancellation date is beyond the period that is agreed in the contract.

ORDER_NOT_EXIST

F

The order does not exist.

KEY_NOT_FOUND

F

The key is not found.

CLIENT_INVALID

F

The client is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

MEDIA_TYPE_NOT_ACCEPTABLE

F

The server does not implement the media type that can be accepted by the client.

MERCHANT_BALANCE_NOT_ENOUGH

F

The merchant's balance is not enough.

Samples

Request

copy
{
 "paymentId":"20191127190741010007013213123",
 "paymentRequestId":"201231231313123123"
}

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S"
 },
 "paymentId":"20191127190741010007013213123",
 "paymentRequestId":"201231231313123123",
 "cancelTime":"2021-06-08T12:12:12+08:00"
}