Capture

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

• Automatic capture
• Manual capture

Note: The South Korean issuer-authenticated cards only supports automatic capture initiated by Antom for you.

Automatic capture

The default value of paymentFactor.captureMode in the pay (One-time Payments) or the createPaymentSession (One-time Payments) API is AUTOMATIC. This means that after the buyer authorizes the payment, Antom will automatically capture the funds for you without any additional confirmation step. The notifyCapture (One-time Payments) API sends you the capture result via an asynchronous notification. You can also inquire about the capture result through the inquiryPayment API.

Manual capture

If you need to decide whether to initiate capture based on risk control results, inventory status, or other business logic after the buyer's authorization, you can set the value of paymentFactor.captureMode in the pay (One-time Payments) or createPaymentSession (One-time Payments) API to MANUAL . In this case, you must call the capture (One-time Payments) API to initiate capture manually. The notifyCapture (One-time Payments) 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 (One-time Payments) API, the key parameters are listed as follows:

The following sample code shows how to call the capture (One-time Payments) 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 (One-time Payments) 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: In the automatic capture mode, how soon will I receive the capture result notification after successful authorization?

A: After successful authorization, Antom will automatically initiate the capture immediately and send the capture result to you via asynchronous notification within seconds.

Q: In the manual capture mode, how long after successful authorization do I need to initiate a capture request?

A: If you manually initiate capture by calling the capture (One-time Payments) API, you must complete the operation within 7 days after successful authorization. If no capture is initiated within 7 days, Antom will automatically void the order and release the frozen funds for the buyer.

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 (One-time Payments) 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 (In the manual capture mode, you must also ensure that the value of transactionRequestId match the value of captureRequestId in your capture request), 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.

Q: In the automatic capture mode, if the timeout period you set through paymentExpireTime is reached, the buyer has completed authorization, but Antom has not yet completed the capture, how will this be handled?
A: Depending on the actual processing status of the transaction, it will be handled as follows:

• If both authorization and capture are completed before the timeout: Antom will send you asynchronous notifications of the authorization result and the capture result. In this case, the capture status in the query result will be S.
• If authorization was initiated before the timeout but the final result has not been returned: After receiving the authorization result from the payment method, Antom will automatically void the transaction. In this case, the authorization status in the query result will be F and no capture status will be returned.
• If authorization is completed before the timeout, but the automatic capture is initiated at or after the timeout: Antom will not initiate capture. You will receive the authorization result notification but no capture result notification. In this caset, there will be no capture status in the query result. It is recommended that you proactively cancel the transaction to release the buyer’s frozen funds.
• If authorization is completed and capture is initiated before the timeout, but the capture result has not been returned: After receiving the capture result from the payment method, Antom will automatically initiate refund for the transaction. In this case, the capture status in the query result will be F, and the refund status will be S.

If you did not set paymentExpireTime, the default timeout period of Antom is 14 minutes. Ensure the buyer completes authorization within this period; the timing of the capture initiation is not affected by this limit.