Capture

Depending on your business needs, choose one of the following methods to capture funds:

• Automatic capture
• Manual capture
  

Automatic capture

You must set the value of paymentFactor.captureMode in the pay (Checkout Payment) or createPaymentSession (Checkout Payment) API to AUTOMATIC. Antom automatically captures funds after the buyer authorizes the payment. The notifyCapture (Checkout Payment) API sends you the capture result via an asynchronous notification. You can also inquire about the capture result through the inquiryPayment API.

Manual capture

You must set the value of paymentFactor.captureMode in the pay (Checkout Payment) or createPaymentSession (Checkout Payment) API to MANUAL, and initiate fund capture by calling the capture (Checkout Payment) API after successful authorization. The notifyCapture (Checkout Payment) API sends you the capture result via an asynchronous notification. You can also inquire about the capture result through the inquiryPayment API.

Integration steps

Start your integration by taking the following steps:

1. Initiate a capture request.
2. Retrieve the capture result.

Step 1: Initiate a capture request Server-side

After successful authorization, intiate a capture using the capture (Checkout Payment) API, the key parameters are listed as follows:

The following sample code shows how to call the capture (Checkout Payment) API:

public static void capture() {
    AlipayCaptureRequest alipayCaptureRequest = new AlipayCaptureRequest();

    Amount amount = Amount.builder().currency("USD").value("2000").build();
    alipayCaptureRequest.setCaptureAmount(amount);

    // replace with your captureRequestId
    String captureRequestId = UUID.randomUUID().toString();
    alipayCaptureRequest.setCaptureRequestId(captureRequestId);

    // replace with your paymentId
    alipayCaptureRequest.setPaymentId("20241212********0211082739");

    AlipayCaptureResponse alipayCaptureResponse = null;
    try {
        alipayCaptureResponse = CLIENT.execute(alipayCaptureRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
    }
}

The following shows the sample code of a capture request: 

{
    "paymentId": "20241212********0211082739",
    "captureRequestId": "4c6c8ffd-*******eeb5af0e3f4",
    "captureAmount": {
        "currency": "USD",
        "value": "2000"
    }
}

The following shows the sample code of a capture response:

{
    "captureAmount": {
        "currency": "USD",
        "value": "2000"
    },
    "captureId": "2024121219********670209694544",
    "captureRequestId": "4c6c8ffd-*******eeb5af0e3f4",
    "captureTime": "2024-12-11T23:34:03-08:00",
    "paymentId": "20241212********0211082739",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    }
}

The table shows the possible values that the result.resultStatus parameter in the response message may return. Please handle the result according to the guidances:

Note: If you did not receive a response message, it might be due to a network timeout. You can call the inquiryPayment API to obtain the capture result or wait for the capture result notification.

Step 2: Receive a capture response Server-side

Use one of the following methods to retrieve the capture result:

• Receive an asynchronous notification
• Inquire about the capture result

Note: When capture succeeds or fails, Antom will send you the asynchronous notification for the corresponding capture result via the webhook URL you configured. If the capture (Checkout Payment) API contains exceptions and returns F, the asynchronous notification will not be triggerred.

{
  "captureAmount": {
    "currency": "USD",
    "value": "2000"
  },
  "captureId": "2024121219********670209694544",
  "captureRequestId": "4c6c8ffd-*******eeb5af0e3f4",
  "captureTime": "2024-12-11T23:34:03-08:00",
  "paymentId": "20241212********0211082739",
  "notifyType": "CAPTURE_RESULT",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

import javax.servlet.http.HttpServletRequest;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import com.alipay.global.api.model.Result;
import com.alipay.global.api.model.ResultStatusType;
import com.alipay.global.api.response.AlipayResponse;
import com.alipay.global.api.tools.WebhookTool;

@RestController
public class PaymentNotifyHandleBySDK {

    /**
     * alipay public key, used to verify signature
     */
    private static final String SERVER_PUBLIC_KEY = "";

    /**
     * payment result notify processor
     * using <a href="https://spring.io">Spring Framework</a>
     *
     * @param request    HttpServletRequest
     * @param notifyBody notify body
     * @return
     */
    @PostMapping("/payNotify")
    public Object payNotifyHandler(HttpServletRequest request, @RequestBody String notifyBody) {

        // retrieve the required parameters from http request
        String requestUri = request.getRequestURI();
        String requestMethod = request.getMethod();

        // retrieve the required parameters from request header 
        String requestTime = request.getHeader("request-time");
        String clientId = request.getHeader("client-id");
        String signature = request.getHeader("signature");

        Result result;
        AlipayResponse response = new AlipayResponse();

        try {
            // verify the signature of notification
            boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, SERVER_PUBLIC_KEY);
            if (!verifyResult) {
                throw new RuntimeException("Invalid notify signature");
            }

            // deserialize the notification body

            // handle your own business logic.

            // acknowledge that the notification is received
            result = new Result("SUCCESS", "success", ResultStatusType.S);

        } catch (Exception e) {
            String errorMsg = e.getMessage();
            // handle error condition
            result = new Result("ERROR", errorMsg, ResultStatusType.F);
        }
        response.setResult(result);
        return ResponseEntity.ok().body(response);
    }

}

{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    }
}

public static void inquiryPayment() {
    AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

    // replace with your paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

{
  "paymentRequestId": "Merchant_Request_ID_XXXXXX"
}

{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "success."
  },
  "paymentId": "2022XXXXXXXXX",
  "paymentResultCode": "SUCCESS",
  "paymentRequestId": "Merchant_Request_ID_XXXXXX",
  "paymentResultMessage": "success",
  "paymentTime": "2022-09-29T07:12:54-07:00",
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "test_test_test_XXXX",
      "transactionAmount": {
        "currency": "BRL",
        "value": "110"
      },
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ],
  "paymentAmount": {
    "currency": "BRL",
    "value": "110"
  },
  "paymentStatus": "SUCCESS"
}

Common Questions

Q: How long after successful authorization do I need to initiate a capture request?

A: You must initiate a capture request within 7 days at the latest after successful authorization. If no action is taken after 7 days, Antom will automatically cancel the order and unfreeze the funds.

Q: Does the capture request support retrying the original request?

A: Yes, it is supported. The capture API implements an idempotency mechanism based on the captureRequestId. The retry rules are as follows:

• If the first response returns resultStatus=S (Success), no retry is needed.
• If the first response returns resultStatus=F (Failure), retries are not supported; repeated requests will still return failure status.
• If the first response returns resultStatus=U (Processing), retries are supported; subsequent requests will return the final processing result (Success S/Failure F).

Q: Does the notification URL for capture results need to be consistent with the authorization result notification URL?

A: Yes. By default, the notification URLs for capture results and authorization results are consistent. If you need to send capture result notifications to an independent URL, you can configure the notification URL in Antom Dashboard. The configuration restrictions for capture notification URLs are as follows:

• Antom Dashboard only supports fixed URL configuration and does not support URLs containing parameter information such as order numbers.
• Currently, passing capture result notification URLs separately through the API is not supported.

Q: What should I do when authorization is completed but I receive a capture failure notification?

A: A capture notification failure means that fund transfer has not occurred definitively. You can cancel the authorization to avoid freezing the buyer's funds and contact Antom Technical Support for troubleshooting.

Q: Does the capture amount need to be consistent with the authorization amount?

A: Yes, they need to be consistent. Currently, only full capture is supported; partial capture is not supported.

Q: After initiating manual capture through the  capture (Checkout Payment) API, if I don't receive a capture result notification, how should I handle it?

A: You can actively query the capture result through the inquiryPayment API. Avoid initiating duplicate capture requests. When an order is in CAPTURE_IN_PROCESS status, duplicate requests will trigger an "amount exceeded" error.

Q: When using the inquiryPayment API to check capture status, what key parameters should I pay attention to?

A: Please pay attention to the following key parameters:

• result: Only indicates the call result of the inquiryPayment API. For APM payments, the payment result of the order should be determined based on paymentStatus (SUCCESS/FAIL/PROCESSING). For card payments, Apple Pay, and Google Pay, paymentStatus only represents the authorization result; shipping decisions should depend on capture results.
• In the transactions[] array, filter for transactions where transactionType = CAPTURE and transactionRequestId completely matches the currently used captureRequestId, then the corresponding transactionResult.resultStatus is the capture result.
• paymentAmount: Used to verify the payment amount.
• paymentId: Represents the payment order ID generated by Antom, used for refunds and reconciliation.

Q: How often should I call the inquiryPayment API?

A: Call the inquiryPayment API continuously at 2-second intervals until you obtain the final payment result or receive an asynchronous payment result notification.