Antom, leading provider of tailored payment solutions

Capture

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:
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
json
{
  "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"
      }
    }
  ]
}
The capture failed
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "FAIL",
      "transactionRequestId": "test_test_test_XXXX",
      "transactionAmount": {
        "currency": "BRL",
        "value": "110"
      },
      "transactionTime": "2022-09-29T07:13:50-07:00",
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "F",
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "General business failure. No retry."
      }
    }
  ]
}
The capture is being processed
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "PROCESSING",
      "transactionRequestId": "test_test_test_XXXX",
      "transactionAmount": {
        "currency": "BRL",
        "value": "110"
      },
      "transactionTime": "2022-09-29T07:13:50-07:00",
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process"
      }
    }
  ]
}