Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

capture (Cashier Payment)

POST /v1/payments/capture

The capture API is used to capture the funds of an authorized payment from a user's account, and then transfer the specified payment amount to the merchant's account. Depending on different scenarios, the authorized payment can be captured in one of the following ways: 

  • Full capture: Capture the total payment amount. 
  • Partial capture: Capture the partial payment amount.  

Structure

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


Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

  • If the data type of a field is Integer and its value is 20, set it as "20". 
  • If the data type of a field is Boolean and its value is true, set it as "true".  

Request parameters

captureRequestId String  REQUIRED

The unique ID that is assigned by the merchant to identify a capture request. Alipay uses this field for idempotence control.  

More information about this field

  • This field is an API idempotency field.For capture requests that are initiated with the same value of captureRequestId and reach a final status (S or F), the same result is to be returned for the request.
  • Maximum length: 64 characters

paymentId String  REQUIRED

The unique ID that is assigned by Alipay to identify a payment.  

More information about this field

  • Maximum length: 64 characters

captureAmount Amount object REQUIRED

The capture amount that the merchant requests to receive in the payment currency.

Show child parameters

isLastCapture Boolean  

Indicates whether it is the last capture. 

  • If the value of this parameter is specified as true, the payment cannot be captured even if the authorization amount is not fully captured. 
  • The value of this parameter is false by default, which means you continue to capture the payment.  

Response parameters

result Result object REQUIRED

The result of the API call. 

Show child parameters

captureRequestId String  

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

This parameter is returned when the capture status is successful.  

More information about this field

  • Maximum length: 64 characters

captureId String  

The unique ID that is assigned by Alipay to identify a capture.

This parameter is returned when the capture status is successful.  

More information about this field

  • Maximum length: 64 characters

paymentId String  

The unique ID that is assigned by Alipay to identify a payment.

This parameter is returned when the capture status is successful.  

More information about this field

  • Maximum length: 64 characters

captureAmount Amount object 

The capture amount that the merchant requests to receive in the payment currency.

This parameter is returned when the capture status is successful.  

Show child parameters

captureTime Datetime  

The time when Alipay captures the payment. 

This parameter is returned when the capture status is successful.  

More information about this field

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

acquirerReferenceNo String  

The unique ID assigned by the non-Alipay acquirer for the transaction.  

More information about this field

  • Maximum length: 64 characters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Request Body

Response

Response Body

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The capture is successful, no further action is needed.  

ACCESS_DENIEDFThe access is denied.

Contact Alipay Technical Support for detailed reasons.  

AUTH_CANCELLEDFThe payment authorization is canceled.

Use a new paymentRequestId to initiate a payment. 

AUTH_EXPIREDFThe payment authorization is expired.

Use a new paymentRequestId to initiate a payment. 

AUTH_NOT_FOUNDFThe payment authorization is not found.

Contact Alipay Technical Support for detailed reasons.  

CAPTURE_AMOUNT_EXCEED_AUTH_LIMITFThe total capture amount exceeds the limit of the authorized payment amount.

Create a new capture request by using an amount less than or equal to the authorized payment amount, or contact Alipay Technical Support. 

CAPTURE_IN_PROCESSFThe capture is processing.

Wait for the notification from Alipay or inquiry about the capture result.  

CURRENCY_NOT_SUPPORTFThe currency is not supported.

Check the currency used in the request, such as the capture currency. If the issue persists, contact Alipay Technical Support for detailed reasons.  

INVALID_CONTRACTFThe parameter values in the contract do not match those in the current transaction.

Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Alipay Technical Support to troubleshoot the issue.  

NO_PAY_OPTIONSFNo payment methods are available.

Contact Alipay Technical Support for detailed reasons.  

ORDER_IS_CANCELEDFThe transaction is canceled.

Use a new paymentRequestId to initiate a payment.  

ORDER_STATUS_INVALIDFThe transaction status is abnormal. The payment cannot be captured.

Check the transaction status. If the values match, contact Alipay Technical Support to troubleshoot the issue.  

PARAM_ILLEGALFThe required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.

Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.  

PAYMENT_COUNT_EXCEED_LIMITFThe number of captures exceeds the limit that is specified by the payment method.

Contact Alipay Technical Support to know the specific limit.  

PROCESS_FAILFThe capture failed.

Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue. 

REPEAT_REQ_INCONSISTENTFThe submitted request exists, and the parameter values of this request are not consistent with those of the existing request.

Ensure all the fields in the requests are the same or use a new paymentRequestId to initiate a payment.  

RISK_REJECTFThe request is rejected because of risk control.

Prompt the user that the request is rejected because of failed risk control. 

USER_AMOUNT_EXCEED_LIMITFThe capture amount exceeds the user payment limit.

Create a new capture by using an amount less than or equal to the user payment limit, or contact the user or the issuing bank. 

USER_BALANCE_NOT_ENOUGHFThe user's balance is insufficient for the capture.

Contact Alipay Technical Support for detailed reasons.  

USER_NOT_EXISTFThe user's account does not exist on the payment method side.

Contact the user or the issuing bank. 

USER_STATUS_ABNORMALFThe user's account status is abnormal on the payment method side.

Contact Alipay Technical Support to know the specific reasons.  

UNKNOWN_EXCEPTIONFThe API call has failed, which is caused by unknown reasons.

Call the interface again to resolve the issue. If the problem persists, contact Alipay Technical Support.