The Checkout Payment service offers comprehensive payment solutions for websites and applications, enabling seamless integration across desktop and mobile platforms. With a one-time integration, businesses can quickly access multiple online payment methods, including e-wallets, bank transfers, and card payments, effectively reducing technical barriers. Buyers are empowered to choose the most convenient and secure payment option according to their personal preferences, ensuring a superior payment experience.

This article describes how to integrate card payment methods using the server-to-server mode. This integration approach is suitable for merchants who require a high level of customization in their payment processes. The server-to-server integration requires PCI compliance; please confirm the specific PCI qualification with the respective acquirers.

The following are the PCI qualification requirements for Antom:

• If your annual card transaction volume is expected to exceed 6 million, complete and submit the PCI Attestation of Compliance (AoC) file for verification.
• If your annual card transaction volume is expected to be below 6 million, complete and submit the PCI DSS Self-Assessment Questionnaires (SAQs) file for verification.

For more information about PCI DSS compliance requirements, see PCI DSS standard.

Note: The hosted mode integration for card payments calls the same set of APIs as the server-to-server mode. If you do not have PCI qualification, or if you do not wish to collect card information yourself, opt for the Hosted mode integration.

User experience

First payment

Saved card payments

Payment flow

The payment flow of the server-to-server card payment integration is composed of the following steps:

1. The buyer enters the card information and select whether to save the card.
2. Create a payment request.
   After the buyer selects a payment method and submits the order, the merchant server calls the pay API to obtain the payment link to complete the payment.
3. Redirect to the 3D authentication page.
   The buyer is redirected to the 3D authentication page to complete identity verification (if frictionless authentication is triggered, verification is not required), and returns to the merchant result page.
4. Obtain the authorized payment result.
   The merchant server receives the payment result notification returned by the payment method, and processes the order based on the returned result.
5. Capture and obtain the capture result.
   You must intiate capture after the authorized payment is successful. You can obtain the capture result using one of the following methods:

• Asynchronous notification: Specify paymentNotifyUrl in the pay API to set the address for receiving asynchronous notifications. When the payment request is successful or expires, APO uses the notifyCapture API to send asynchronous notifications to you.
• Synchronous inquiry: Call the inquiryPayment API to check the payment request status.

Note: If you have activated the same payment method with multiple acquirers, you can configure the payment routing rule on APO Dashboard. If no payment routing rules are set, APO will use random routing rules.

Integration preparations

Integration steps

Start your integration by taking the following steps.

1. (Optional) Display the payment methods
2. Authorize a payment
3. (Optional) Redirect to 3D authorization URL
4. Obtain the authorized payment result
5. Capture and obtain the capture result
   

Step 1: (Optional) Display payment methods Client-side

Step 2: Authorize a payment Server-side

When the buyer selects a payment method, you need to collect the key order information, such as the buyer's payment method information, order information, device information, and payment amount. Call the pay API, and submit an authorization request for payment.

1. Call the pay API

The following sample code shows how to call the pay API:

public static void payByCardServer2Server() {
    AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
    alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

    // replace with your paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPayRequest.setPaymentRequestId(paymentRequestId);

    // set amount
    Amount amount = Amount.builder().currency("SGD").value("4200").build();
    alipayPayRequest.setPaymentAmount(amount);

    // set payment methods
    PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("CARD").build();
    alipayPayRequest.setPaymentMethod(paymentMethod);

    // card info
    Map<String, Object> paymentMethodMetaData = new HashMap<String, Object>();
     paymentMethodMetaData.put("tokenizeMode", ASKFORCONSENT);
     paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);

    // replace with your orderId
    String orderId = UUID.randomUUID().toString();

    // set buyer info
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // set order info
    Order order = Order.builder().referenceOrderId(orderId)
        .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
    alipayPayRequest.setOrder(order);

    // set environment info
    Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("1.2.3.4").build();
    alipayPayRequest.setEnv(env);

    // set authorization capture payment mode
    PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
    alipayPayRequest.setPaymentFactor(paymentFactor);

    // replace with your notify url
    alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

    // replace with your redirect url
    alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    // process payment
    AlipayPayResponse alipayPayResponse = null;
    try {
        alipayPayResponse = CLIENT.execute(alipayPayRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

2. Create a payment request

Initiating a payment request involves the following key parameters:

Note: For more information about the full parameters and other requirements of specific payment methods, refer to the pay API.

The following shows the sample code of a payment request:

{
  "env":{
    "browserInfo":{
      "acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "javaEnabled":false,
      "javaScriptEnabled":false,
      "language":"en",
      "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"
    },
    "clientIp":"172.*.*.*",
    "colorDepth":24,
    "deviceId":"d0e9ee6d-be3a-487d-b514-69495000be72",
    "deviceLanguage":"en",
    "screenHeight":723,
    "screenWidth":1536,
    "terminalType":"WEB",
    "timeZoneOffset":0
  },
  "order":{
    "buyer":{
      "buyerEmail":"ken***@gmail.com",
      "buyerName":{
        "firstName":"*******",
        "lastName":"schmitt "
      },
      "buyerPhoneNo":"7046518433",
      "buyerRegistrationTime":"2022-01-10T20:33:07+08:00",
      "referenceBuyerId":"2095667"
    },
    "goods":[
      {
        "deliveryMethodType":"PHYSICAL",
        "goodsCategory":"Bikini Sets",
        "goodsName":"V-neck Strawberry Knotted Tankini Cheeky Bikini Set",
        "goodsQuantity":"1",
        "goodsUnitAmount":{
          "currency":"USD",
          "value":"2290"
        },
        "goodsUrl":"https://m.shopcider.com/product/detail?pid=114496585",
        "referenceGoodsId":"114496585"
      },
      {
        "deliveryMethodType":"PHYSICAL",
        "goodsCategory":"3 Piece Bikini Sets",
        "goodsName":"V-neck Floral Halter Cheeky Bikini Swimsuit With Floral Cover Up Skirt",
        "goodsQuantity":"1",
        "goodsUnitAmount":{
          "currency":"USD",
          "value":"2790"
        },
        "goodsUrl":"https://m.shopcider.com/product/detail?pid=111038664",
        "referenceGoodsId":"111038664"
      },
      {
        "deliveryMethodType":"PHYSICAL",
        "goodsCategory":"3 Piece Bikini Sets",
        "goodsName":"V-neck Halter Floral Tie Side Bikini Swimsuit With Sarong",
        "goodsQuantity":"1",
        "goodsUnitAmount":{
          "currency":"USD",
          "value":"2790"
        },
        "goodsUrl":"https://m.shopcider.com/product/detail?pid=107371032",
        "referenceGoodsId":"107371032"
      },
      {
        "deliveryMethodType":"PHYSICAL",
        "goodsCategory":"One-pieces ",
        "goodsName":"Shaping Lettuce Trim Cut Out Shell Chain O-Ring One Piece Swimsuit",
        "goodsQuantity":"1",
        "goodsUnitAmount":{
          "currency":"USD",
          "value":"2490"
        },
        "goodsUrl":"https://m.shopcider.com/product/detail?pid=114267374",
        "referenceGoodsId":"114267374"
      },
      {
        "deliveryMethodType":"PHYSICAL",
        "goodsCategory":"One-pieces ",
        "goodsName":"Shaping Halter Floral Bowknot Ruched One Piece Swimsuit",
        "goodsQuantity":"1",
        "goodsUnitAmount":{
          "currency":"USD",
          "value":"1990"
        },
        "goodsUrl":"https://m.shopcider.com/product/detail?pid=107966234",
        "referenceGoodsId":"107966234"
      }],
    "orderAmount":{
      "currency":"USD",
      "value":"13184"
    },
    "orderDescription":"Shop in Cider.",
    "referenceOrderId":"8203426867",
    "shipping":{
      "shipToEmail":"ken***@gmail.com",
      "shippingAddress":{
        "address1":"*************************",
        "city":"Waxhaw",
        "region":"US",
        "state":"NC",
        "zipCode":"28173"
      },
      "shippingName":{
        "firstName":"*******",
        "lastName":"schmitt "
      },
      "shippingPhoneNo":"7046518433"
    }
  },
  "paymentAmount":{
    "currency":"USD",
    "value":"13184"
  },
  "paymentFactor":{
    "captureMode":"MANUAL",
    "isAuthorization":true
  },
  "paymentMethod":{
    "paymentMethodMetaData":{
      "billingAddress":{
        "address1":"*******************",
        "address2":"",
        "city":"waxhaw",
        "region":"US",
        "state":"NC",
        "zipCode":"28173"
      },
      "cardNo":"************8842",
      "cardholderName":{
        "firstName":"*******",
        "lastName":"schmitt "
      },
      "cvv":"***",
      "expiryMonth":"**",
      "expiryYear":"****"
    },
    "paymentMethodType":"CARD"
  },
  "paymentNotifyUrl":"https://pay.shopcider.com/pay/v2/notify/callback?platform=ALIPAY",
  "paymentRedirectUrl":"https://www.shopcider.com/payment/success?tradeNo=20250515141372578176868806656&oid=8203426867&payType=ALIPAY_CARD_DIRECT_US&ovt=e51e7e02c94340e7809f5b9a3768ffe4",
  "paymentRequestId":"20250515141372578176868806656",
  "productCode":"CASHIER_PAYMENT",
  "settlementStrategy":{
    "settlementCurrency":"USD"
  }
}

The following shows the sample code of a response, which contains the following key parameters:

• acquirerInfo: The information of the acquirer. It is recommended to save the information of the acquirer (acquirerInfo), refer to Order number management for specific reasons.
• result.resultStatus: The status of the authorized payment.
• normalUrl: The URL used to redirect to the 3D authentication page.

{
  "acquirerInfo":{
    "acquirerMerchantId":"2181110021840423",
    "acquirerName":"ALIPAY",
    "acquirerResultCode":"SUCCESS",
    "acquirerResultMessage":"success",
    "acquirerTransactionId":"20250514114010800100181020233302045",
    "referenceRequestId":"20250514141372220148107038720"
  },
  "authExpiryTime":"2025-05-13T23:33:01-07:00",
  "paymentAmount":{
    "currency":"USD",
    "value":"1339"
  },
  "paymentCreateTime":"2025-05-13T23:32:59-07:00",
  "paymentId":"20250514114010800100181020233302045",
  "paymentRequestId":"20250514141372220148107038720",
  "paymentResultInfo":{
    "avsResultRaw":"Y",
    "cardBrand":"VISA",
    "cardNo":"************9484",
    "cvvResultRaw":"Y",
    "networkTransactionId":"385134235816498",
    "threeDSResult":{
      "cavv":"AQAAAAAAPTYgKe8AmdDhgoYAAAA=",
      "eci":"07"
    }
  },
  "paymentTime":"2025-05-13T23:33:01-07:00",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

{
  "result": {
    "resultCode": "ACCESS_DENIED",
    "resultMessage": "Access is denied.",
    "resultStatus": "F"
  }
}

{
    "authExpiryTime": "2025-02-27T15:15:57+08:00",
    "normalUrl": "https://ac.alipay.com/page/sandbox/stone-infostaging.html?paymentId=20250220194010800190188000014991264&code=golcashier99ed8d93-efcf-4fe7-b9a1-4bb1152d6ad4sandbox&golSandbox=true&pspName=CARD&county=SG",
    "paymentActionForm": "{\"method\":\"GET\",\"paymentActionFormType\":\"RedirectActionForm\",\"redirectUrl\":\"https://ac.alipay.com/page/sandbox/stone-infostaging.html?paymentId=20250220194010800190188000014991264&code=golcashier99ed8d93-efcf-4fe7-b9a1-4bb1152d6ad4sandbox&golSandbox=true&pspName=CARD&county=SG\"}",
    "paymentAmount": {
        "currency": "HKD",
        "value": "30000"
    },
    "paymentCreateTime": "2025-02-20T15:15:57+08:00",
    "paymentId": "20250220194010800190188000014991264",
    "paymentRequestId": "13eIlShnRH5mKYtqFa2kvfht2IXdx1XoOg0S9jd3pMWzg3iOBwoXCv1YuEUyno0A",
    "redirectActionForm": {
        "method": "GET",
        "redirectUrl": "https://ac.alipay.com/page/sandbox/stone-infostaging.html?paymentId=20250220194010800190188000014991264&code=golcashier99ed8d93-efcf-4fe7-b9a1-4bb1152d6ad4sandbox&golSandbox=true&pspName=CARD&county=SG"
    },
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "Payment is processing.",
        "resultStatus": "U"
    }
}

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 retrieve the payment result, or wait for the asynchronous payment result notifications.

Common Questions

Q: What is paymentId ？

A: If you need to store the corresponding order number for future refunds and reconciliation, you can specify paymentId. 

Q: What is the information in acquirerInfo and how do I use it?

A: This parameter indicates the information about the acquirer, refer to Order number management for more information.

Q: How to configure terminalType？

A: The valid values of terminalType are:

• WEB: The client-side terminal type is a website, which is opened via a PC browser.
• WAP: The client-side terminal type is an H5 page, which is opened via a mobile browser. Additionally, fill in the corresponding env.osType parameter as ANDROID or IOS based on the buyer's mobile device. 
• APP: The client-side terminal type is a mobile application.

Q: How to identify if a transaction requires 3D authentication？

A: You can decide whether the transaction requires 3D authentication based on the current risk and dispute considerations. Valid values for configuring is3DSAuthentication are:

• true: APO passes the transaction as 3D-secured to the corresponding  acquirers.
• false: If the parameter is not configured or set to false, APO passes the transaction as non-3D-secured to the corresponding acquirers. However, the final processing decision depends on the acquirer.

Q: In the case where a transaction does not require 3D authentication, will the payment result of the authorized payment be returned directly?
A: No. The returned authorized payment results may include the following situations:

• The payment is being processed:

• If the redirect URL is not returned, you need to wait for the asynchronous payment result notifications or call the inquiryPayment API to retrieve the payment result. You must not mark it as a payment failure.
• If the redirect URL is returned, you need to redirect the buyer to the URL.

• No response: It might be due to a network timeout. You can call the inquiryPayment API to retrieve the payment result, or wait for the asynchronous payment result notifications. You must not mark it as a payment failure.
• The payment is successful: You can proceed with initiating capture.
• The payment failed: Guide the buyer to try again.

Step 3: (Optional) Redirect to the 3D authentication page Client-side

Once the merchant’s server obtains the normalUrl returned by APO, it should pass normalUrl to the frontend, which will then redirect the buyer to the 3D authentication page.

Note: This step is not applicable if the pay API returns result.resultStatus with a value of S or F, as the authorized payment stage has reached its final state.

if (serverResponse.normalUrl != null) {
    window.open(serverResponse.normalUrl, '_blank');
}

window.location.href = URL;

// Initialize webview configuration
WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc]init];
// Initialize webView 
WKWebView *webView = [[WKWebView alloc]initWithFrame:CGRectMake(0, 0, [UIScreen mainScreen].bounds.size.width, [UIScreen mainScreen].bounds.size.height) configuration:configuration];
webView.navigationDelegate = self;
//Load the payment method URL
[webView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:Url]]];
[self.view addSubview:self.webView];

WebView webView = findViewById(R.id.webview);
//Set webview
webView.setWebViewClient(new WebViewClient() {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
        view.loadUrl(request.getUrl().toString());
        return super.shouldOverrideUrlLoading(view, request);
    }});

WebSettings webSettings = webView.getSettings();
//Enable javascript
webSettings.setJavaScriptEnabled(true);
//Enable scaling
webSettings.setSupportZoom(true);
//Enable scaling controls (buttons)
webSettings.setBuiltInZoomControls(true);
//Webview has two cache modes. Cache is not used here.
webSettings.setCacheMode(WebSettings.LOAD_NO_CACHE);
//Allow JavaScript to open a new tab (false by default)
webSettings.setJavaScriptCanOpenWindowsAutomatically(true);
//Allow JavaScript to load local storage
webSettings.setDomStorageEnabled(true);
//WAP cache size (settings are not needed)
//webSettings.setAppCacheMaxSize(1024 * 1024 * 8);
//WAP cache path
String absolutePath = getApplicationContext().getCacheDir().getAbsolutePath();
//WAP cache size
webSettings.setAppCachePath(absolutePath);
//Set whether to allow WebView to access files (true by default)
webSettings.setAllowFileAccess(true);
//Allow WAP cache to be saved
webSettings.setAppCacheEnabled(true);
//In preview mode, if the page width exceeds the WebView display, scale down the page to fit WebView (false by default)
webSettings.setLoadWithOverviewMode(true);
//Support the viewport HTML meta tag
webSettings.setUseWideViewPort(true);
//Load the payment method URL
webView.loadUrl(Url);

Different terminal returns different normalUrl. APO will decide which normalUrl to return based on the paymentMethod and terminalType information provided by you.

Web

App

Common Questions

Q: How to handle the returned 3D authentication page URL?

A: For web (Web/WAP), you can directly process the redirection; For mobile, you can open the page in a web browser; however, please note that in some cases, specific card issuers may require their own banking app to be launched, which cannot be universally guaranteed in all integration scenarios.

Q: How should the content of the payment result page be displayed?

A:

• Both successful and failed payments may provide an option to redirect from the payment method back to the merchant’s page. Therefore, do not fix paymentRedirectUrl as the payment success page; instead, base it on the result returned by your server to prevent confusion for buyers.
• If the transaction is initiated from a mobile application, you need to set paymentRedirectUrl as the scheme address of the merchant application.

Q: Does the redirection to the merchant result page indicate a successful payment?

A: No. You cannot determine payment success solely based on the redirection to the merchant page, and APO will not append any payment result parameters indicating the payment result to paymentRedirectUrl. Redirection to the merchant result page may occur in the following situations:

• After the buyer successfully completes a payment, they may not be redirected to the merchant’s page due to network or other issues.
• Even if the buyer has not completed the payment, they may also return to the merchant page through the entry point provided by the payment method.

Step 4: Obtain the authorized payment result Server-side

1. Set the webhook URL to receive notifications

You can choose one of following methods to set the webhook URL to receive notifications:

• If each of your order has a unique notification URL, we recommend to set the webhook URL in each individual request. You can pass the asynchronous notification receiving URL for the specific order through the paymentNotifyUrl parameter in the pay API.
• If all your orders share a unified notification URL, you can set the webhook URL on APO Dashboard through Developer > Notification Address.

Note:

• If you set the webhook URL through both the API and APO Dashboard, the one set in the pay API takes precedence.
• If the buyer fails to verify their identity after being redirected to the 3D authentication page, APO will only send an asynchronous notification after the order is closed. The default payment tiemout depends on the acquirer.

The following is the notification request sample code:

{
  "acquirerInfo":{
    "acquirerMerchantId":"WF_wallet_UK",
    "acquirerName":"ADYEN",
    "acquirerTransactionId":"PK6K679WDZS2K8F3",
    "referenceRequestId":"N2025021716031300000460202933868"
  },
  "acquirerReferenceNo":"PK6K679WDZS2K8F3",
  },
  "notifyType":"PAYMENT_RESULT",
  "paymentAmount":{
    "currency":"GBP",
    "value":"1523"
  },
  "paymentCreateTime":"2025-02-16T21:48:05-08:00",
  "paymentId":"20250217164010890100111460207325722",
  "paymentRequestId":"2025021786031300001258802935146",
  "paymentResultInfo":{
    "avsResultRaw":"Y",
    "cardBin":"439654",
    "cardBrand":"VISA",
    "cardNo":"************6044",
    "cvvResultRaw":"M",
    "fingerprint":"2a1b042f23d1a0927175e4fb8893ab9be5f0ffeff54ed87b88f433671fa67cf4",
    "funding":"DEBIT",
    "issuerName":"WISE PAYMENTS LIMITED",
    "issuingCountry":"GB",
    "threeDSResult":{
      "cavv":"N/A",
      "eci":"N/A",
      "threeDSType":"INTERNAL",
      "xid":"N/A"
    }
  },
  "paymentTime":"2025-02-16T21:48:06-08:00",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

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

2. Verify asynchronous notifications

If you receive an asynchronous notification from APO, you are required to return the response in the Sample code format, but you do not need to countersign the response.

You need to verify the signature of the payment notification sent by APO.

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
            
            // update the order status with notify result

            // respond the server 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);
    }

}

You do not need to countersign the response of the result notification. However, you must respond to each notification request in the following fixed format, regardless of whether the payment is successful or not.

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

Common Questions

Q: When will the notification be sent?

A: The sending time depends on whether the payment is completed. If the payment is completed, APO will send an asynchronous notification immediately after receiving notification from the corresponding acquirer.

Q: Will the asynchronous notification be re-sent?

A: Yes, the asynchronous notification will be re-sent automatically within 24 hours for the following cases:

• If you didn't receive the asynchronous notification due to network reasons.
• If you receive an asynchronous notification from APO, but you didn't make a response to the notification in the Sample code format.

The notification can be re-sent up to 8 times or until a correct response is received to terminate delivery. The sending intervals are as follows: 0 minutes, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, and 15 hours.

Q: Can the shipping be based on resultStatus with the value S? 

A: No, the shipping should be based on the capture result. 

Q: Is signature verification required after receiving payment result notification?

A: Yes. APO will send a secure callback request to you after signature verification. When verifying the signature, please note that the message to be verified should be assembled according to the standard processing: <http-method> <http-uri> <client-id>.<request-time>.<request-body>. Especially for <request-body>, the value should be taken directly instead of parsing JSON and then assembling.

Step 5: Capture and obtain the capture result

You can configure the paymentFactor.captureMode parameter in the pay API to opt for automatic capture or manual capture. You can obtain the capture result through an asynchronous notification or inquire about the capture result by calling the inquiryPayment API. For more information, see Capture.

It is recommended to save the information of the acquirer (acquirerInfo), refer to Order number management for specific reasons. The following code shows an example of a capture result response when inquiring about the capture result:

{
  "paymentResultCode":"SUCCESS",
  "paymentRequestId":"G153202503171022523041",
  "paymentResultInfo":{
    "lastFour":"1358",
    "funding":"CREDIT",
    "issuerName":"ORIENT CORPORATION",
    "expiryMonth":"**",
    "threeDSResult":{
      "cavv":"",
      "xid":"649335d6-1858-4532-8a6e-0579e1b78a2a",
      "threeDSType":"INTERNAL",
      "eci":"05",
      "threeDSVersion":"2.2.0"
    },
    "expiryYear":"**",
    "cardNo":"************1358",
    "cardBin":"428067",
    "holdName":"NIHEI SHUNSUKE",
    "issuingCountry":"JP",
    "avsResultRaw":"I",
    "fingerprint":"a28f7dd0713e2f1d4e9ccae8853f5c0abca5154a03a6559cd985eb409857579b",
    "networkTransactionId":"465076088338711",
    "cardBrand":"VISA",
    "cvvResultRaw":""
  },
  "transactions":[
    {
      "transactionType":"CAPTURE",
      "transactionStatus":"SUCCESS",
      "transactionRequestId":"G153202503171022523041",
      "transactionAmount":{
        "currency":"JPY",
        "value":"120"
      },
      "transactionTime":"2025-03-16T19:27:17-07:00",
      "acquirerInfo":{
        "referenceRequestId":"2025031719031301000600278847294",
        "acquirerTransactionId":"act_yv3fchmu3bre3l3tui5y352yby",
        "acquirerMerchantId":"pc_6cpbmm5qderubjraxrygjehf5q",
        "acquirerName":"CHECKOUT"
      },
      "transactionId":"20250317194010890100111600255676857",
      "transactionResult":{
        "resultStatus":"S",
        "resultCode":"SUCCESS",
        "resultMessage":"success"
      }
    }
  ],
  "paymentAmount":{
    "currency":"JPY",
    "value":"120"
  },
  "acquirerReferenceNo":"pay_6tmvamfcxp5ujbbfjeopyz6v7q",
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMessage":"success."
  },
  "paymentId":"20250317194010890100111600255689113",
  "paymentResultMessage":"success.",
  "paymentTime":"2025-03-16T19:27:17-07:00",
  "acquirerInfo":{
    "referenceRequestId":"2025031719031300000600278825707",
    "acquirerTransactionId":"pay_6tmvamfcxp5ujbbfjeopyz6v7q",
    "acquirerMerchantId":"pc_6cpbmm5qderubjraxrygjehf5q",
    "acquirerName":"CHECKOUT"
  },
  "paymentStatus":"SUCCESS",
  "paymentCreateTime":"2025-03-16T19:26:42-07:00"
}

After payment

Inquire about the authorized payment result

In addition to obtaining the buyer's payment result through the asynchronous notification, you can retrieve the corresponding payment result through the payments inquiry service. You can call the inquiryPayment API and use the paymentRequestId value of the payment to check the payment status.

The following code shows how to call the inquiryPayment API:

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
    }
}

The following code shows an example of a request:

{
    "paymentRequestId": "PAY_202506*****942875"
}

It is recommended to save the information on acquirers (acquirerInfo), refer to Order number management for specific reasons. The following code shows an example of a response:

{
  "paymentResultCode":"SUCCESS",
  "paymentRequestId":"G153202503171022523041",
  "paymentResultInfo":{
    "lastFour":"1358",
    "funding":"CREDIT",
    "issuerName":"ORIENT CORPORATION",
    "expiryMonth":"**",
    "threeDSResult":{
      "cavv":"",
      "xid":"649335d6-1858-4532-8a6e-0579e1b78a2a",
      "threeDSType":"INTERNAL",
      "eci":"05",
      "threeDSVersion":"2.2.0"
    },
    "expiryYear":"**",
    "cardNo":"************1358",
    "cardBin":"428067",
    "holdName":"NIHEI SHUNSUKE",
    "issuingCountry":"JP",
    "avsResultRaw":"I",
    "fingerprint":"a28f7dd0713e2f1d4e9ccae8853f5c0abca5154a03a6559cd985eb409857579b",
    "networkTransactionId":"465076088338711",
    "cardBrand":"VISA",
    "cvvResultRaw":""
  },
  "paymentAmount":{
    "currency":"JPY",
    "value":"120"
  },
  "acquirerReferenceNo":"pay_6tmvamfcxp5ujbbfjeopyz6v7q",
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMessage":"success."
  },
  "paymentId":"2025031719401089010011160025568****",
  "paymentResultMessage":"success.",
  "paymentTime":"2025-03-16T19:27:17-07:00",
  "acquirerInfo":{
    "referenceRequestId":"202503171903130000060027882****",
    "acquirerTransactionId":"pay_6tmvamfcxp5ujbbfjeopyz****",
    "acquirerMerchantId":"pc_6cpbmm5qderubjraxrygje****",
    "acquirerName":"CHECKOUT"
  },
  "paymentStatus":"SUCCESS",
  "paymentCreateTime":"2025-03-16T19:26:42-07:00"
}

The table shows the possible values of paymentStatus returned in the response. Please handle the result according to the guidances: 

Common Questions

Q: What are the key parameters in the inquiry that I need to use?

A: Pay attention to the following key parameters:

• paymentStatus: You need to determine the authorized payment result based on this parameter.
• paymentAmount: indicates the payment amount.

Q: What is the recommended frequency for calling the inquiryPayment API?

A: It is recommended to use polling with an interval of 2 seconds. Begin polling immediately after calling the pay API, and continue the inquiry until the final payment result is obtained or the payment result asynchronous notification is received.

Cancel Server-side

If you need to cancel a transaction, you can use the cancel API. For more information, see Cancel.

Refund Server-side

To learn about APO refund rules and how to initiate a refund for a successful transaction, see Refund for more information.

Dispute Server-side

When a buyer chooses to pay with a card, a dispute may occur. To learn more, see Dispute.

Reconciliation

After the transaction is completed, use the financial reports provided by APO for reconciliation. For more information on how to reconcile and the settlement rules of APO, please refer to Reconciliation.