Capture

2025-01-08 07:17

You need to initiate fund capture by calling the capture API (POST/v1/payments/capture) within seven days after successful authorization. Otherwise, Antom automatically unfreezes the authorized funds of the payment. For some card payment methods, one authorization supports one or multiple capture. The total capture amount should be less than or equal to the total authorized amount.

Note: The capture amount of American cards needs to 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 must be less than or equal to 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

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.

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), Antom sends you the asynchronous notification through the notifyCapture notification. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, Antom 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 Antom 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

If the capture is successful, the parameter earliestSettlementTime is also returned, which indicates the earliest time at which the transaction can initiate a split and settlement.

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 indicate 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",
      "earliestSettlementTime": "2023-07-04T15:20:15-07:00",
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ]
}

If the capture is successful, the parameter earliestSettlementTime is also returned, which indicates the earliest time at which the transaction can initiate a split and settlement.