Capture

2024-12-18 16:36

APO automatically handles funds capture for you by default. If you specify the value of paymentFactor.captureMode to MANUAL when calling the pay API or createPaymentSession API, you must capture the funds of the payment by calling the capture API.

Automatic capture: APO automatically captures funds immediately after the user authorizes the payment. The capture result is then communicated to you via an asynchronous notification. Automatic capture is activated when one of the following conditions is met:

You set the value of paymentFactor.captureMode in the pay API or createPaymentSession API to AUTOMATIC.
You leave the value of paymentFactor.captureMode in the pay API or createPaymentSession API empty or you do not pass in this parameter.

Manual capture: You must initiate fund capture by calling the capture API after successful authorization. The total capture amount must be equal to the total authorized amount.

Note: For card payments, it is recommended to confirm the successful capture result before shipping.

Manually 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 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:

Group 22.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), APO sends you the asynchronous notification through the notifyCapture notification. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, APO 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 APO assigns to an order.
result	The capture result.
acquirerReferenceNo	The relevant information of the acquiring institution handling this transaction, including the institution name, transaction number on the institution side

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 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"
            },
            "transactionId": "2022XXXXXXXX",
            "transactionResult": {
                "resultStatus": "S",
                "resultCode": "SUCCESS",
                "resultMessage": "success"
            }
        }
    ]
}