Capture

2023-06-01 03:03

You must request to capture the payment by calling the capture API (POST/v1/payments/capture) within seven days after the authorization succeeds, otherwise Alipay automatically unfreezes the authorized funds. Some card payment methods support multiple captures of an authorized fund. The total capture amount must be no greater than the total authorized amount.

Note: For American cards, the capture amount must be equal to the authorized amount.

Initiate a capture request

The key request parameters in the capture API (POST/v1/payments/capture) are shown in the following table:

Parameter	Description
captureRequestId	A unique identifier that you assign to a capture request.
paymentId	A unique identifier that Alipay assigns to an order.
captureAmount	The capture amount, which must be no greater than the total authorized amount.

Table 1. key parameters in the capture API

Obtain a capture result

In the response returned through the capture API, the value of the resultStatus parameter indicates the capture result.

S: The capture is successful.
F: The capture failed.
U: You need to obtain the capture result by receiving an asynchronous notification through the notifyCapture notification or inquiring about the capture result.

You can handle the response according to the logic shown in the following figure:

9@3x.png

Figure 1. Values of resultStatus in the response

Asynchronous notification

You can obtain the capture result by receiving an asynchronous notification through the notifyCapture notification. When a final capture status is achieved (that is, when the capture is successful or failed), Alipay sends you the asynchronous notification through the notifyCapture notification. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, Alipay resends the notification until a correct response is received.

Key parameters in the asynchronous notification:

Parameter	Description
notifyType	The value is `CAPTURE_RESULT`.
paymentId	The unique identifier that Alipay assigns to an order.
result	The capture result.
acquirerReferenceNo	If you have integrated the capabilities of receiving card payments in Singapore or Hong Kong, the acquirer number is provided in the notification.

Table 2. Key parameters in the notifyCapture notification

Configure a notification receiving address:

To receive the asynchronous notification, you must configure the notification address in either of the following two ways:

Specify paymentNotifyUrl in the pay API.
Edit Notification URL in the Integration Settings tab of Alipay Developer Center.

Inquire about the capture status

The asynchronous notification and the synchronous redirection can both fail to be received or implemented. We recommend that you inquire about the capture status by calling the inquiryPayment API. In the response returned through the inquiryPayment API, transactions indicates the capture status. See the following table for details:

Parameter	Description
transactions.transationType	The value is `CAPTURE`. It indicates the capture status.
transactions.transactionResult	The capture result.

Table 3. Key child parameters of transactions

The value of transactions indicates the capture status. See the following code samples for details:

The capture is successful

The capture failed

The capture is being processed

copy
{
    "transactions": [
        {
            "transactionType": "CAPTURE",
            "transactionStatus": "SUCCESS",
            "transactionRequestId": "test_test_test_XXXX",
            "transactionAmount": {
                "currency": "BRL",
                "value": "110"
            },
            "transactionTime": "2022-09-29T07:13:50-07:00",
            "transactionId": "2022XXXXXXXX",
            "transactionResult": {
                "resultStatus": "S",
                "resultCode": "SUCCESS",
                "resultMessage": "success"
            }
        }
    ]
}