# Hosted recurring payments > Follow the guide to complete hosted Antom Checkout Page (CKP) subscription integration to accept recurring payments. Antom Checkout Page (CKP) is a user-friendly, low-code payment solution that simplifies global transactions. Supporting a wide range of payment methods, CKP meets the needs of different markets and business scenarios. With minimal setup, you can quickly create a professional, feature-rich checkout page that offers buyers a smooth and convenient payment experience while significantly improving payment integration efficiency and driving business growth. This guide shows you how to integrate CKP through an API, where your buyers are redirected to the Antom Checkout Page to make payment without the need for additional page configurations. ## User experience {#pkToD} The following illustrates the user experience for first-time subscription and subsequent payments when integrating the Checkout Page: **Tab: First-time subscription** **Tab: PC** Buyers redirect from the merchant page to the Antom Checkout Page: ![First-time subscription using hosted Antom Checkout Page for PC terminal](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/d0778a91-e9ae-46b5-a168-3c1d7980c297.png) Some payment methods require redirecting to specific third-party payment pages: ![Third-party payment page redirect during first-time subscription via hosted CKP for PC terminal](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/e9d20dfb-a324-4814-9c94-aaa5d7762caf.png) Payments made using stored card: ![Stored card payment for subscription via hosted CKP for PC terminal](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/3285fc97-c877-47e2-a84b-84dd8b9b72c2.png) **Tab: Mobile** Buyers redirect from the merchant page to the Antom Checkout Page: ![First-time subscription using hosted Antom Checkout Page (CKP) on a mobile device](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/ae04f004-207e-4d24-a827-ddec939a6255.png) Some payment methods require redirecting to specific third-party payment pages: ![Third-party payment page redirect during first-time subscription via hosted CKP on mobile](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/5b0824f1-01ac-413d-9702-be4205731ffe.png) Payments made using stored card: ![Stored card payment for subscription via hosted CKP on mobile](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/daec56d5-b9c1-41f9-a5da-2f98c964a82d.png) **Tab: Subsequent deductions** Subsequent recurring deductions will be initiated by the Antom server. The merchant's server processes subscription renewals by receiving payment notifications, enabling service extensions for users without any page interaction. ## Payment flow {#m8FIl} The process for subscription payments using hosted CKP includes the following steps: **Tab: Card payments, Google Pay, and Apple Pay** **Tab: First-time subscription** The following shows the process of initial subscription payment via card payments, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md): ![Card, Google Pay, and Apple Pay first-time subscription via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/fab67ace-bcdb-4deb-96a2-2456b3ed428c.png) 1. **The buyer enters the subscription page and initiates payments.** 2. **Create** **a payment session request.** You can call the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API to obtain a payment session. 3. **Handle Antom Checkout Page URL.** The merchant front end loads the Antom Checkout Page URL. On this page, the buyer selects the payment method and completes the payment. After the payment is processed, the buyer is redirected to the Checkout Page's result page and then redirected to the merchant result page. Alternatively, y ou can configure on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) to redirect the buyer directly to the merchant result page. 4. **Obtain authorization payment results.** You can retrieve payment results through one of the following methods: - Asynchronous notifications: Specify *paymentNotifyUrl* parameter on [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API or configure on [Antom Dashboard](https://docs.antom.com/ac/merchant_service/notification.md) o set the address for receiving asynchronous notifications. Antom sends an asynchronous notification through the [**notifyPayment**](https://docs.antom.com/docs/ac/ams/paymentrn_online.md) API when a payment request succeeds or expires. - Synchronous inquiry: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to query the authorization payment status. > **[INFO]** **Note**: For card payments and some APMs (such as [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Pay by bank](https://docs.antom.com/ac/antomop/pay_by_bank.md)), an authorized-capture model is used. Steps 1 to 4 only complete the authorization stage-where the buyer completes payment using a card and the funds are temporarily frozen. To transfer the funds to your account, you must complete the capture step. A successful capture result should be used as the basis for shipping goods. 5. **Capture and obtain the capture result.** By default, Antom automatically handles fund capture on your behalf. You can also manually [capture](https://docs.antom.com/ac/cashierpay/capture.md) funds by calling the [**capture (One-time Payments)**](https://docs.antom.com/ac/ams/capture.md) API. The capture result can be obtained through one of the following methods: - Asynchronous notification: Specify *paymentNotifyUrl* in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API or configure on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) to set the address for receiving asynchronous notifications. Upon capture completion, Antom will send you asynchronous notifications via the [**notifyCapture (One-time Payments)**](https://docs.antom.com/ac/ams/notify_capture.md) API. - Synchronous inquiry: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to check the payment status. 6. **Obtain subscription notifications.** After the subscription takes effect, Antom will send you the first-time subscription notifications and subscription renewal notifications. **Tab: Subsequent deductions** The following shows the process for subsequent periodic deductions via card payments, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md): ![Card, Google Pay, and Apple Pay subsequent recurring deductions via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/cfe149bb-7b3d-409a-a5e7-2349a07157f9.png) 1. **Antom server initiates a deduction from the issuer bank or the payment method.** 2. **Obtain the authorization payment result.** You can obtain the authorization results through one of the following two methods: - Asynchronous notification: Specify *paymentNotifyUrl* in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API or configure on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) to set the address for receiving asynchronous notifications. When the payment is successful or expires, Antom will use [**notifyPayment**](https://docs.antom.com/ac/ams/paymentrn_online.md) to send asynchronous notifications to you. - Synchronous inquiry: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to check the payment or authorization status. > **[INFO]** **Note** : For card payments and certain APM payment methods (such as [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) and [Pay by Bank](https://docs.antom.com/ac/antomop/pay_by_bank.md)), these payment methods follow an authorized-capture mode. The steps above only complete the authorization phase, indicates that the buyer has completed the payment using their card, and the funds are in a frozen state. To transfer the buyer's frozen funds to your account, you must integrate the capture step. The successful capture result will serve as the basis for shipping goods. 3. **Capture and obtain the capture result.** In the subsequent deductions, Antom automatically handles fund capture by default. The capture result can be obtained through one of the following methods: - Asynchronous notification: Specify *paymentNotifyUrl* in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API or configure on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) to set the address for receiving asynchronous notifications. Upon capture completion, Antom will send you asynchronous notifications via the [**notifyCapture (One-time Payments)**](https://docs.antom.com/ac/ams/notify_capture.md) API. - Synchronous inquiry: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to check the capture status. 4. **Obtain subscription notifications.** After the deduction is successful or fails, Antom will send you a subscription deduction notification. **Tab: APMs** **Tab: First-time subscription** The following shows the process of initial subscription payment via APMs: ![APM first-time subscription via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/dd9f7016-3682-4a30-938b-2e15031d45b4.png) 1. **The buyer enters the subscription page and initiates payments.** 2. **Create** **a payment session request.** You can call the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API to obtain a payment session. 3. **Handle Antom Checkout Page URL.** The merchant front end loads the Antom Checkout Page URL. On this page, the buyer selects the payment method and completes the payment. After the payment is processed, the buyer is redirected to the Checkout Page's result page and then redirected to the merchant result page. Alternatively, y ou can configure on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) to redirect the buyer directly to the merchant result page. 4. **Obtain authorization payment results.** You can retrieve payment results through one of the following methods: - Asynchronous notifications: Specify *paymentNotifyUrl* parameter in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API or configure on [Antom Dashboard](https://docs.antom.com/ac/merchant_service/notification.md) o set the address for receiving asynchronous notifications. Antom sends an asynchronous notification through the [**notifyPayment**](https://docs.antom.com/docs/ac/ams/paymentrn_online.md) API when a payment request succeeds or expires. - Synchronous inquiry: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to query the authorization payment status. 5. **Obtain subscription notifications.** After the subscription takes effect, Antom will send you the first-time subscription notifications and subscription renewal notifications. **Tab: Subsequent deductions** The following shows the process for subsequent periodic deductions via APMs: ![APM subsequent recurring deductions via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/f1e12df7-ecf3-46e9-aee3-0e434573723e.png) 1. **Antom server initiates a deduction from the payment method.** 2. **Obtain the payment result.** You can obtain the payment results through one of the following two methods: - Asynchronous notification: Specify *paymentNotifyUrl* in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API or configure on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) to set the address for receiving asynchronous notifications. When the payment is successful or expires, Antom will use [**notifyPayment**](https://docs.antom.com/ac/ams/paymentrn_online.md) to send asynchronous notifications to you. - Synchronous inquiry: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to check the payment or authorization status. 3. **Obtain subscription notifications.** After the deduction is successful or fails, Antom will send you a subscription deduction notification. ## Subscription lifecycle {#EO8Un} The following images illustrate the subscription lifecycle for different payment methods: **Tab: Card payments, Google Pay, and Apple Pay** The image below shows the entire subscription lifecycle for card payments, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), including subscription creation, payment method binding, completion of the first payment, and refund processing when necessary. The process ensures the valid activation of subscriptions and the security and transparency of all payment transactions. ![Subscription lifecycle diagram for card payments, Google Pay, and Apple Pay via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/8c3996e7-7f5d-4b29-a7fa-4090b0625cc9.png) ![Subscription status transition diagram for card payments, Google Pay, and Apple Pay via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/e47c3487-b53f-4fa3-bd2d-a49502715bbe.png) **Tab: APMs** The image below shows the entire subscription lifecycle for APMs, including subscription creation, payment method binding, completion of the first payment, and refund processing when necessary. The process ensures the valid activation of subscriptions and the security and transparency of all payment transactions. ![Subscription lifecycle diagram for APMs via hosted CKP](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/c0a75784-680a-4bd1-a93b-1b87390dd355.png) ## Integration preparations {#i42B7} Before you start integrating, read the [Integration Guide](https://docs.antom.com/integration_guide_en.md) and [API Overview](https://docs.antom.com/ac/ams/api_fund.md) documents to understand the integration steps of the server-side API and the precautions for calling the API. Furthermore, ensure that the following prerequisites are met: - Obtain a client ID - Complete the key configuration - Complete the configuration of *paymentNotifyUrl* to receive the asynchronous notification - Integrate the server-side SDK package, install the server-side library, and initialize a request instance. For more details, refer to [Server-side SDKs](https://docs.antom.com/ac/sdks/server_sdks.md) . ## Integration Steps {#I4xsR} Follow these steps to start the integration: 1. Create a payment session 2. Redirect to Antom Checkout Page 3. Notify authorization/payment result 4. (Optional) Capture and obtain the capture result 5. Obtain subscription notifications ### Step 1: Create a payment session **[Server-side]** {#A0cut} You can call the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API and pass in the order information. After creating the payment session, you will be redirected to the Antom Checkout Page. Creating a payment session includes the following parameters: | **Parameter type** | **Parameter** | **Required** | **Description** | | --- | --- | --- | --- | | Basic parameter | *paymentRequestId* | Yes | The unique authorized payment request ID. | | *paymentAmount.currency* | Yes | The payment currency. | | | *paymentAmount.value* | Yes | The payment amount. Set in the smallest unit of currency; JPY and KRW are in yuan, while others are in cents. | | | *paymentMethod.paymentMethodType* | Yes | Payment method enumeration value. | | | *settlementStrategy.settlementCurrency* | No | The settlement currency. | | | *productCode* | Yes | The product code. In this scenario, this parameter is fixed to `CASHIER_PAYMENT` . | | | *paymentRedirectUrl* | Yes | Merchant's payment result page. You need to provide an HTTPS address for dynamic rendering based on the payment result. | | | *paymentNotifyUrl* | No | The notification URL for payment authorization must be an HTTPS address. This parameter can be passed through the API or set as a fixed value on Antom Dashboard. If both are set, the value passed through the API takes precedence. | | | *productScene* | Yes | The scene code. This parameter is fixed to `CHECKOUT_PAYMENT` . | | | Device parameter | *env.terminalType* | Yes | Specify the type of terminal for the buyer to initiate the transaction: - `WEB` : The client terminal type is a website, accessed through a PC browser. - `WAP` : The client terminal type is an H5 page, accessed through a mobile browser. - `APP` : The client terminal type is a mobile application. | | *env.clientIp* | Yes | Buyer's IP address. | | | Order parameter | *order.orderAmount* | Yes | The order amount. | | *order.referenceOrderId* | Yes | Merchant's order number. | | | *order.orderDescription* | Yes | Merchant's order description. | | | *order.buyer* | Yes | Merchant's buyer information. At least one of the following three pieces of information is required: - *order.buyer.referenceBuyerId* - *order.buyer.buyerPhoneNo* - *order.buyer.buyerEmail* | | | Subscription parameter | *subscriptionInfo.subscriptionDescription* | Yes | The subscription description. | | *subscriptionInfo.subscriptionStartTime* | Yes | The effective time of the subscription. The format is similar to 2019-11-27T12:01:01+08:00, and +08:00 represents the East Eighth District. | | | *subscriptionInfo.subscriptionNotifyUrl* | Yes | The address to receive subscription notifications. You need to enter the HTTPS address. | | | *subscriptionInfo.periodRule* | Yes | The subscription cycle, which supports four types of cycles: `YEAR` , `MONTH` , `WEEK` , and `DAY` . | | | *subscriptionInfo.subscriptionExpiryTime* | No | A specific date and time after which the created subscription expires. After the subscription expires, the order must be terminated. The default value for this parameter is: - 7 days, if the payment method is card payment, [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), or [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md) (calculated from the time the subscription creation request is sent). - 80 minutes, if the payment method is APMs (calculated from the time the subscription creation request is sent). > **[INFO]** **Note** : For APMs, you need to set the subscription expiration time to be greater than 74 minutes. | | | 3D Secure authentication parameter | *availablePaymentMethod.paymentMethodMetaData.* *is3DSAuthentication* | No | You need to decide whether to perform 3D Secure (3DS) authentication based on the current transaction's risk and chargeback situation. For more details, please refer to the [3D Secure authentication](https://docs.antom.com/ac/subscriptionpay/HOSTEDCKP.md?locale=en-us#B2p2C) . Valid values are: - `true` : Indicates that the transaction initiates 3DS authentication. - `false` : Indicates that the transaction does not perform 3DS authentication. If this parameter is empty or not provided, it defaults to this value. > **[INFO]** **Note** : In card payment scenarios, it must be set to `true` for 3DS transactions to ensure identity verification for the first card payment. | The above parameters are the basic parameters for creating a payment session. For complete and additional requirements for specific payment methods, please refer to [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) . The following sample code shows how to call the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API: ```java public static void createPaymentSession() { AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest(); alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT); alipayPaymentSessionRequest.setProductScene(ProductSceneConstants.CHECKOUT_PAYMENT); // Set subscription information SubscriptionInfo subscriptionInfo = new SubscriptionInfo(); subscriptionInfo.setSubscriptionDescription("TEST_SUBSCRIPTION"); DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssXXX"); subscriptionInfo.setSubscriptionStartTime(ZonedDateTime.now().format(formatter)); subscriptionInfo.setSubscriptionEndTime(ZonedDateTime.now().plusYears(1).format(formatter)); subscriptionInfo.setSubscriptionNotifyUrl("https://your.example.com/subscriptionNotify"); // Set subscription period rule PeriodRule periodRule = new PeriodRule(); periodRule.setPeriodType("YEAR"); periodRule.setPeriodCount(1); subscriptionInfo.setPeriodRule(periodRule); alipayPaymentSessionRequest.setSubscriptionInfo(subscriptionInfo); // Set payment amount Amount amount = Amount.builder() .currency("SGD") .value("6000") .build(); alipayPaymentSessionRequest.setPaymentAmount(amount); // Replace with your paymentRequestId String paymentRequestId = UUID.randomUUID().toString(); alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId); // Replace with your orderId String orderId = UUID.randomUUID().toString(); // Set buyer information Buyer buyer = Buyer.builder() .referenceBuyerId("yourBuyerId") .build(); // Set order information Order order = Order.builder() .referenceOrderId(orderId) .orderDescription("antom ckp testing order") .orderAmount(amount) .buyer(buyer) .build(); alipayPaymentSessionRequest.setOrder(order); // Set available payment method AvailablePaymentMethod availablePaymentMethod = new AvailablePaymentMethod(); HashMap methodData = new HashMap<>(); methodData.put("is3DSAuthentication", true); List paymentMethodTypeList = new ArrayList<>(); PaymentMethodTypeItem paymentMethodTypeItem = new PaymentMethodTypeItem(); paymentMethodTypeItem.setPaymentMethodType("CARD"); availablePaymentMethod.setPaymentMethodTypeList(paymentMethodTypeList); availablePaymentMethod.setPaymentMethodMetaData(methodData); alipayPaymentSessionRequest.setAvailablePaymentMethod(availablePaymentMethod); // Set authorization capture mode PaymentFactor paymentFactor = PaymentFactor.builder() .isAuthorization(true) .build(); alipayPaymentSessionRequest.setPaymentFactor(paymentFactor); // Set environment information Env env = Env.builder() .terminalType(TerminalType.WEB) .clientIp("1.2.3.4") .build(); alipayPaymentSessionRequest.setEnv(env); // Replace with your notification URL // Or configure your notification URL here: https://dashboard.antom.com/global-payments/developers/iNotify alipayPaymentSessionRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com/payment/receiveNotify"); // Replace with your redirect URL alipayPaymentSessionRequest.setPaymentRedirectUrl( "http://localhost:8080/index.html?paymentRequestId=" + paymentRequestId); // Set settlement strategy // Replace with your existing settlement currency SettlementStrategy settlementStrategy = SettlementStrategy.builder() .settlementCurrency("USD") .build(); alipayPaymentSessionRequest.setSettlementStrategy(settlementStrategy); // Replace with your clientId alipayPaymentSessionRequest.setClientId(clientId); AlipayPaymentSessionResponse alipayPaymentSessionResponse; try { alipayPaymentSessionResponse = defaultAlipayClient.execute(alipayPaymentSessionRequest); } catch (AlipayApiException e) { String errorMsg = e.getMessage(); // Handle error condition } } ``` The following shows the sample code of a request: ```json { "env": { "clientIp": "1.*.*.*", "terminalType": "WEB" }, "order": { "buyer": { "referenceBuyerId": "yourBuyerId" }, "orderAmount": { "currency": "SGD", "value": "6000" }, "orderDescription": "antom ckp testing order", "referenceOrderId": "9aec4249-1934-4294-8c30-1993a157da5f" }, "paymentAmount": { "currency": "SGD", "value": "6000" }, "paymentFactor": { "isAuthorization": true }, "availablePaymentMethod": { "paymentMethodMetaData": { "is3DSAuthentication": true }, "paymentMethodTypeList": [] }, "paymentNotifyUrl": "http://www.yourNotifyUrl.com/payment/receiveNotify", "paymentRedirectUrl": "http://www.yourRedirectUrl.com/payment/redirect", "paymentRequestId": "601e5c9e-78b3-455e-84bb-ee41f88c6c07", "productCode": "CASHIER_PAYMENT", "productScene": "CHECKOUT_PAYMENT", "settlementStrategy": { "settlementCurrency": "USD" }, "subscriptionInfo": { "periodRule": { "periodCount": 1, "periodType": "YEAR" }, "subscriptionDescription": "TEST_SUBSCRIPTION", "subscriptionEndTime": "2027-03-12T10:38:54+08:00", "subscriptionNotifyUrl": "https://your.example.com/subscription/notify", "subscriptionStartTime": "2026-03-12T10:38:54+08:00" } } ``` The following shows the sample code of a response, which contains the following parameters: - *paymentSessionData* : Payment session data to be returned to the front end. - *paymentSessionExpiryTime* : The specific date and time after which the payment session will expire. - *normalUrl* : The URL used to redirect to the Checkout Page. ```JSON { "normalUrl": "https://checkout.antom.com/checkout-page/pages/payment/index.html?sessionData=cwnCzs7PcMfU03oKT1F%2BPHrpJmhr5k%2FF8nAcL4GP4PIin2bG4nFyF0NmqIOyf8Lt7Rh1%2BmgE27Csjx3Xhr8lkA%3D%3D%26%26SG%26%26188%26%26eyJlbGlnaWJsZUVhc3lQYXlNYXJrZXRpbmciOmZhbHNlLCJleHRlbmRJbmZvIjoie1wiT1BFTl9NVUxUSV9QQVlNRU5UX0FCSUxJVFlcIjpcInRydWVcIixcImRpc3BsYXlBbnRvbUxvZ29cIjpcInRydWVcIn0iLCJuZWVkQWNjb3VudENvbmZpcm1QYWdlIjpmYWxzZSwicGF5bWVudFNlc3Npb25Db25maWciOnsicGF5bWVudE1ldGhvZENhdGVnb3J5VHlwZSI6IkFMTCIsInByb2R1Y3RTY2VuZSI6IkNIRUNLT1VUX1BBWU1FTlQiLCJwcm9kdWN0U2NlbmVWZXJzaW9uIjoiMS4wIn0sInNlY3VyaXR5Q29uZmlnIjp7ImFwcElkIjoiIiwiYXBwTmFtZSI6Ik9uZUFjY291bnQiLCJiaXpUb2tlbiI6IjZUY2RicjJyRjNyUFl4NGhrVnJIcWJ2aiIsImdhdGV3YXkiOiJodHRwczovL2ltZ3Mtc2VhLmFsaXBheS5jb20vbWd3Lmh0bSIsImg1Z2F0ZXdheSI6Imh0dHBzOi8vb3Blbi1zZWEtZ2xvYmFsLmFsaXBheS5jb20vYXBpL29wZW4vcmlza19jbGllbnQiLCJ3b3JrU3BhY2VJZCI6IiJ9LCJza2lwUmV******GF5bWVudE1ldGhvZCI6ZmFsc2V9&shadow=true", "paymentSessionData": "4dChA3EBSSxaN9XOjRZ0zN3C8l8x******RPDA5O+7TYW/kJ9tR76f**********vPiEEUII0uZciWVbjNIpxElA==&&SG&&188&&eyJlbGlnaWJsZUVhc3lQYXlNYXJrZXRpbmciOmZhbHNlLCJleHRlbmRJbmZvIjoie1wiT1BFTl9NVUxUSV9QQVlNRU5UX0FCSUxJVFlcIjpcInRydWVcIixcImRpc3BsYXlMYXlvdXRcIjpcIkxFRlRfT1JERVJfQU5EX1JJR0hUX1BBWU1FTlRcIixcInRoZW1lVHlwZVwiOlwiQ1VTVE9NSVpFXCIsXCJkaXNwbGF5QW50b21Mb2dvXCI6XCJmYWxzZVwifSIsIm5lZWRBY2NvdW50Q29uZmlybVBhZ2UiOmZhbHNlLCJwYXltZW50U2Vzc2lvbkNvbmZpZyI6eyJwYXltZW50TWV0aG9kQ2F0ZWdvcnlUeXBlIjoiQUxMIiwicHJvZHVjdFNjZW5lIjoiQ0hFQ0tPVVRfUEFZTUVOVCIsInByb2R1Y3RTY2VuZVZlcnNpb24iOiIxLjAifSwic2VjdXJpdHlDb25maWciOnsiYXBwSWQiOiIiLCJhcHBOYW1lIjoiT25lQWNjb3VudCIsImJpelRva2VuIjoiNlRjZGJyMnJGM3JQWXg0aGtWckhxYnZqIiwiZ2F0ZXdheSI6Imh0dHBzOi8vaW1ncy1zZWEuYWxpcGF5LmNvbS9tZ3cuaHRtIiwiaDVnYXRld2F5IjoiaHR0cHM6Ly9vcGVuLXNlYS1nbG9iYWwuYWxpcGF5LmNvbS9hcGkvb3Blbi9yaXNrX2NsaWVudCIsIndvcmtTcGFjZUlkIjoiIn0sInNraXBSZW5kZXJQYXltZW50TWV0aG9kIjpmYWxzZX0=", "paymentSessionExpiryTime": "2026-03-12T11:38:59+08:00", "paymentSessionId": "4dChA3EBSSxaN9XOjRZ0zN3C8l8x*********DA5O+7S4zYs/gYmYI0w5X1FgRTmT", "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: | ***result.resultStatus*** | **Message** | **Further actions** | | --- | --- | --- | | `S` | Indicates that payment session creation succeeded. | Obtain the Antom Checkout Page URL ( *normalUrl* ) and return to the merchant's front end. For detailed steps, please refer to [Step 2](#rJXV8) . | | `F` | Indicates that the payment session creation failed. | Please check and verify whether the current API required request parameters (including header parameters and body parameters) are correctly passed and valid. | | `U` | Indicates that payment session creation failed for unknown reasons. | Please change the *paymentRequestId* and call the API again to resolve the issue. Please contact Antom technical support i f the problem persists . | > **[INFO]** **Note** : If you did not receive a response message, it might be due to a network timeout. Please change the *paymentRequestId* and call the API again to resolve the issue. ### Step 2: Redirect to Antom Checkout Page ( *normalUrl* ) **[Client-side]** {#rJXV8} After the merchant server obtains the Checkout Page URL ( *normalUrl)* returned by Antom, it passes this URL to the front end, and the merchant front end redirects to the Antom Checkout Page. The following is a sample code for loading *normalUrl* on the merchant front end: **Tab: Web** ```javascript if (serverResponse.normalUrl != null) { window.open(serverResponse.normalUrl, '_blank'); } ``` **Tab: WAP** ```javascript window.location.href = URL; ``` The image below shows the page rendering effect of the redirected Antom Checkout Page: ![Screenshot of rendered Antom Checkout Page (CKP) showing the subscription payment interface](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144356525/1768377581578-85873515-cc9c-4511-a852-a23eb1f08bb0.png) #### 3D Secure authentication page {#z6HtI} The initial transaction requires buyer participation for identity authentication, which ensures the security of subsequent recurring charges without the buyer's presence. The 3D Secure (3DS) authentication requirements for the initial transaction are as follows: | **Payment method type** | **3DS authentication requirements for initial transaction** | **Action** | | --- | --- | --- | | Card payments | Whether the merchant or Antom collects card information, the initial transaction must complete 3DS authentication to verify the buyer's identity. | Set the parameter *is3DSAuthentication* to `true` in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API. | | [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md) | If Antom is entrusted to decrypt the *paymentToken* , the initial transaction must complete 3DS transaction to verify the buyer's identity. | Set the parameter *is3DSAuthentication* to `true` in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API. > **[INFO]** **Note** : If the decrypted card information by Antom is a DPAN, the authentication process will automatically proceed without requiring secondary identity verification from the buyer. | | [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) | If Antom is entrusted to decrypt the *ApplePayPaymentToken* , the initial transaction must complete 3DS transaction to verify the buyer's identity. | Set the parameter *is3DSAuthentication* to `true` in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API. | > **[INFO]** **Common questions** > > > **Q: What are the considerations for passing the** ***paymentRedirectUrl*** **parameter?** > A: It is set to an HTTPS address by default. Additionally, special characters in the URL must be encoded; otherwise, payment exceptions may occur. > > > **Q: How is the payment result page displayed?** > A: You need to specify the *paymentRedirectUrl* parameter in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API to provide an HTTPS address. This address is used to display the payment result on the merchant side. In both success and failure scenarios, there may be options to redirect back to the merchant page from the payment method side. Therefore, avoid hardcoding the *paymentRedirectUrl* as a "subscription creation success page". Instead, dynamically display content based on the server-side response to prevent buyer confusion. > > > **Q: Does redirecting to the merchant result page indicate successful subscription creation?** > A: Redirecting to the merchant page alone cannot confirm successful subscription creation. The following three scenarios should be considered: > > - After successful payment, the buyer may fail to redirect to the merchant page due to network issues. > - Even if the buyer does not complete the payment, they may still redirect to the merchant page using options provided by the payment method side. > - Even if the buyer completes the payment, the subscription may not activate due to failed capture. ### Step 3: Notify authorization or payment result **[Server-side]** {#nyIgr} During the payment processing flow, Antom will send you respective result notifications based on the specific payment method type. - For card payments, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) transactions, Antom sends authorization result notifications to inform you whether the authorization was successful. A capture request is only triggered after a successful authorization. Please use the capture result as the basis for shipping goods. - For APM scenarios, Antom sends payment result notifications when a payment either succeeds or fails. **Tab: Card payments, Google Pay, and Apple Pay** Regardless of whether the authorization is successful or not, Antom will send the payment result to you via the [**notifyPayment**](https://docs.antom.com/ac/ams/notify_subpayment.md) API. Please follow the steps below to receive authorization payment result notifications: 1. Set the webhook URL for receiving notifications: Antom allows you to specify the URL in the *paymentNotifyUrl* parameter of the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API. If the URL is the same for all payments, you can also configure it on Antom Dashboard. Below is a code example of the asynchronous notification request body: ```json { "actualPaymentAmount": { "currency": "USD", "value": "1" }, "cardInfo": { "avsResultRaw": "U", "cardBrand": "VISA", "cardCategory": "CONSUMER", "cardNo": "************0550", "credentialTypeUsed": "PAN", "cvvResultRaw": "M", "funding": "PREPAID", "issuingCountry": "MY", "networkTransactionId": "202510090****09b937936376", "paymentMethodRegion": "GLOBAL", "threeDSResult": { "cavv": "mockCavv", "challengeCancel": "", "challenged": true, "dsTransactionId": "cce18b6e-b55e-40ff-814c-619b4598****", "eci": "02", "threeDSOffered": true, "threeDSVersion": "2.1.0", "threeDStransactionStatusReason": "" } }, "notifyType": "PAYMENT_RESULT", "paymentAmount": { "currency": "USD", "value": "1" }, "paymentCreateTime": "2025-10-08T19:11:20-07:00", "paymentId": "202510091940108****01889B0255128143", "paymentMethodType": "GOOGLEPAY", "paymentRequestId": "PAYMENT_2025100****050687_AUTO", "paymentResultInfo": { "avsResultRaw": "U", "cardBrand": "VISA", "cardCategory": "CONSUMER", "cardNo": "************0550", "credentialTypeUsed": "PAN", "cvvResultRaw": "M", "funding": "PREPAID", "issuingCountry": "MY", "networkTransactionId": "202510090****09b937936376", "paymentMethodRegion": "GLOBAL", "threeDSResult": { "cavv": "mockCavv", "challengeCancel": "", "challenged": true, "dsTransactionId": "cce18b6e-b55e-40ff-814c-619b4598****", "eci": "02", "threeDSOffered": true, "threeDSVersion": "2.1.0", "threeDStransactionStatusReason": "" } }, "paymentTime": "2025-10-08T19:11:38-07:00", "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ``` 2\. Verify asynchronous notifications If you receive an asynchronous notification from Antom, you are required to return the response in the format of [Return a receipt acknowledgement message](https://docs.antom.com/ac/tokenized/notifications.md#vQK5A) , but you do not need to countersign the response. You need to verify the signature of the notification sent by Antom according to the following steps: ```java /** * receive notify * * @param request request * @param notifyBody notify body * @return Result */ @PostMapping("/receivePaymentNotify") @ResponseBody public Result receivePaymentNotify(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"); try { // verify the signature of notification boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, ANTOM_PUBLIC_KEY); if (!verifyResult) { throw new RuntimeException("Invalid notify signature"); } // deserialize the notification body AlipaySubscriptionPayNotify paymentNotify = JSON.parseObject(notifyBody, AlipaySubscriptionPayNotify.class); if (paymentNotify != null && "SUCCESS".equals(paymentNotify.getResult().getResultCode())) { // handle your own business logic // e.g.：Save the user's payment information by linking the subscriptionRequestId with the user ID. System.out.println("receive payment notify: " + JSON.toJSONString(paymentNotify)); return Result.builder().resultCode("SUCCESS").resultMessage("success.").resultStatus(ResultStatusType.S).build(); } } catch (Exception e) { return Result.builder().resultCode("FAIL").resultMessage("fail.").resultStatus(ResultStatusType.F).build(); } return Result.builder().resultCode("SYSTEM_ERROR").resultMessage("system error.").resultStatus(ResultStatusType.F).build(); } ``` 3. Respond to the notification result. You must respond to each notification request in the following fixed format, regardless of whether the payment is successful or not. Otherwise, Antom will resend the asynchronous notification. ```json { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } } ``` **Tab: APMs** Regardless of whether the payment is successful or not, Antom will send the payment result to you via the [**notifyPayment**](https://docs.antom.com/ac/ams/notify_subpayment.md) API. Please follow the steps below to receive payment result notifications: 1. Set the webhook URL for receiving notifications: Antom allows you to specify the URL in the *paymentNotifyUrl* parameter of the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API. If the URL is the same for all payments, you can also configure it on Antom Dashboard. Below is a code example of the asynchronous notification request body: ```json { "actualPaymentAmount": { "currency": "MYR", "value": "498" }, "notifyType": "PAYMENT_RESULT", "paymentAmount": { "currency": "MYR", "value": "498" }, "paymentCreateTime": "2025-11-04T02:07:37-08:00", "paymentId": "202511041940108001****8330226108041", "paymentRequestId": "eshop_2108220418892243_5110404369713****", "paymentResultInfo": {}, "paymentTime": "2025-11-04T02:07:51-08:00", "pspCustomerInfo": { "pspCustomerId": "1000001****34758", "pspName": "TNG" }, "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ``` 2\. Verify asynchronous notifications If you receive an asynchronous notification from Antom, you are required to return the response in the format of [Return a receipt acknowledgement message](https://docs.antom.com/ac/tokenized/notifications.md#vQK5A) , but you do not need to countersign the response. You need to verify the signature of the notification sent by Antom according to the following steps: ```java /** * receive notify * * @param request request * @param notifyBody notify body * @return Result */ @PostMapping("/receivePaymentNotify") @ResponseBody public Result receivePaymentNotify(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"); try { // verify the signature of notification boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, ANTOM_PUBLIC_KEY); if (!verifyResult) { throw new RuntimeException("Invalid notify signature"); } // deserialize the notification body AlipaySubscriptionPayNotify paymentNotify = JSON.parseObject(notifyBody, AlipaySubscriptionPayNotify.class); if (paymentNotify != null && "SUCCESS".equals(paymentNotify.getResult().getResultCode())) { // handle your own business logic // e.g.：Save the user's payment information by linking the subscriptionRequestId with the user ID. System.out.println("receive payment notify: " + JSON.toJSONString(paymentNotify)); return Result.builder().resultCode("SUCCESS").resultMessage("success.").resultStatus(ResultStatusType.S).build(); } } catch (Exception e) { return Result.builder().resultCode("FAIL").resultMessage("fail.").resultStatus(ResultStatusType.F).build(); } return Result.builder().resultCode("SYSTEM_ERROR").resultMessage("system error.").resultStatus(ResultStatusType.F).build(); } ``` 3. Respond to the notification result. You must respond to each notification request in the following fixed format, regardless of whether the payment is successful or not. Otherwise, Antom will resend the asynchronous notification. ```json { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } } ``` ### (Optional) Step 4: Capture and obtain the capture result **[Server-side]** {#YUhhd} > **[INFO]** **Note** ： > > - Card payments require capture. Capture can only be initiated with successful authorized payments. > - Certain APMs, such as [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Pay by bank](https://docs.antom.com/ac/antomop/pay_by_bank.md), require capture. Capture can only be initiated with successful authorized payments. If payment is successful, Antom will automatically initiate capture for you, while you can also initiate capture manually. Antom will subsequently send you the capture result via the [**notifyCapture (One-time Payments)**](https://docs.antom.com/ac/ams/notify_capture.md) API. You may also proactively query the capture result. You should decide whether to ship goods based on the capture result. For specific operations, refer to [Capture](https://docs.antom.com/ac/cashierpay/capture.md) . ### Step 5: Obtain subscription notifications **[Server-side]** {#b2IMR} Once a subscription is activated, Antom will send the following notifications to you: - [First-time subscription notifications](#uHh8I) - [Subscription renewal notifications](#DeF0l) #### First-time subscription Notifications {#uHh8I} Antom will send the following event notifications via HTTPS to the webhook URL configured in the API or the Antom Dashboard: | **Notification Type** | **API** | **Request message info** | | --- | --- | --- | | Subscription status notifications | After the subscription takes effect, Antom will send you the subscription result notification via the [**notifySubscription**](https://docs.antom.com/ac/ams/notify_sub.md) API. | - When the value of the *subscriptionNotificationType* in the request message is `CREATE` , the *subscriptionStatus* determines whether the subscription is active ( `ACTIVE` ) or terminated ( `TERMINATED` ). - When the value of the *subscriptionNotificationType* in the request message is `TERMINATE` , the subscription is terminated. | | Current deduction result notifications | After the subscription is successfully activated or renewed, Antom will send you the current subscription deduction result via the [**notifyPayment**](https://docs.antom.com/ac/ams/notify_subpayment.md) API. | When the value of *notifyType* in the request message is `PAYMENT_RESULT` , the *result.resultStatus* parameter indicates whether the current payment deduction is successful (S) or failed (F). | **Tab: Subscription status notifications** Follow these steps to receive subscription status notifications: 1. Set the webhook URL to receive notifications: Configure via the *subscriptionInfo.subscriptionNotifyUrl* parameter in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API. Below are examples for two types of subscription status notifications: - When the value of *subscriptionNotificationType* is `CREATE` , determine the subscription status based on the value of *subscriptionStatus* : - `ACTIVE` : Indicates that the subscription is active. - `TERMINATED` : Indicates that the subscription is terminated. ```json { "periodRule": { "periodCount": 1, "periodType": "MONTH" }, "subscriptionEndTime": "2074-02-20T01:16:17-08:00", "subscriptionId": "2024091419000000****000050000010226", "subscriptionNotificationType": "CREATE", "subscriptionRequestId": "SUBSCRIPTION_20244****410165oo009851_AUTO", "subscriptionStartTime": "2024-09-13T19:30:17-07:00", "subscriptionStatus": "ACTIVE" } ``` - When the value of *subscriptionNotificationType* is `TERMINATE` , the subscription is terminated. ```json { "periodRule": { "periodCount": 1, "periodType": "WEEK" }, "subscriptionId": "2025102619******00000160000671943", "subscriptionLastUpdateTime": "2025-10-26T09:51:13-07:00", "subscriptionNotificationType": "TERMINATE", "subscriptionRequestId": "PR_en_****176", "subscriptionStartTime": "2025-10-26T10:01:13-07:00", "subscriptionStatus": "TERMINATED" } ``` 2. Verify asynchronous notifications. If you receive an asynchronous notification from Antom, you are required to return the response in the format of [Return a receipt acknowledgement message](https://docs.antom.com/ac/tokenized/notifications.md#vQK5A) , but you do not need to countersign the response. You need to verify the signature of the notification sent by Antom according to the following steps: ```java /** * receive subscription notify * * @param request request * @param notifyBody notify body * @return Result */ @PostMapping("/receiveSubscriptionNotify") @ResponseBody public Result receiveSubscriptionNotify(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"); try { // verify the signature of notification boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, ANTOM_PUBLIC_KEY); if (!verifyResult) { throw new RuntimeException("Invalid notify signature"); } // deserialize the notification body AlipaySubscriptionNotify subscriptionNotify = JSON.parseObject(notifyBody, AlipaySubscriptionNotify.class); if (subscriptionNotify != null && SubscriptionNotificationType.CREATE.equals(subscriptionNotify.getSubscriptionNotificationType())) { // handle your own business logic // e.g.：Save the user's payment information by linking the subscriptionRequestId with the user ID. System.out.println("receive subscription notify: " + JSON.toJSONString(subscriptionNotify)); return Result.builder().resultCode("SUCCESS").resultMessage("success.").resultStatus(ResultStatusType.S).build(); } } catch (Exception e) { return Result.builder().resultCode("FAIL").resultMessage("fail.").resultStatus(ResultStatusType.F).build(); } return Result.builder().resultCode("SYSTEM_ERROR").resultMessage("system error.").resultStatus(ResultStatusType.F).build(); } ``` 3. Respond to the notification result. You must respond to each notification request in the following fixed format, regardless of whether the payment is successful or not. Otherwise, Antom will resend the asynchronous notification. ```json { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } } ``` **Tab: Current deduction result notifications** Follow these steps to receive current deduction result notifications: 1. Set the webhook URL to receive notifications: Configure via the *paymentNotifyUrl* parameter in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API and on Antom Dashboard. Below is the code example of the asynchronous notification request body: ```json { "paymentAmount": { "currency": "USD", "value": "1" }, "notifyType": "PAYMENT_RESULT", "paymentCreateTime": "2025-10-08T19:10:51-07:00", "paymentId": "202510091940108****01889B0255128143", "paymentTime": "2025-10-08T19:11:40-07:00", "periodEndTime": "2025-08-02T19:15:29-07:00", "periodStartTime": "2025-07-26T19:15:29-07:00", "phaseNo": "1", "result": { "resultCode": "SUCCESS", "resultMessage": "success", "resultStatus": "S" }, "subscriptionId": "202510091900000000****00E0000032897", "subscriptionRequestId": "PAYMENT_202510****1050687_AUTO" } ``` Key parameter description: - *notifyType* : The notification type, with the value as `PAYMENT_RESULT` . - *phaseNo* : The installment number of the current subscription cycle. - *periodStartTime* : The start time of the current subscription cycle. - *periodEndTime* : The end time of the current subscription cycle. - *paymentAmount* : The amount deducted for each periodic payment. 2. Verify asynchronous notifications. If you receive an asynchronous notification from Antom, you are required to return the response in the format of [Return a receipt acknowledgement message](https://docs.antom.com/ac/tokenized/notifications.md#vQK5A) , but you do not need to countersign the response. You need to verify the signature of the notification sent by Antom according to the following steps: ```java /** * receive subscription notify * * @param request request * @param notifyBody notify body * @return Result */ @PostMapping("/receiveSubscriptionNotify") @ResponseBody public Result receiveSubscriptionNotify(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"); try { // verify the signature of notification boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, ANTOM_PUBLIC_KEY); if (!verifyResult) { throw new RuntimeException("Invalid notify signature"); } // deserialize the notification body AlipaySubscriptionNotify subscriptionNotify = JSON.parseObject(notifyBody, AlipaySubscriptionNotify.class); if (subscriptionNotify != null && SubscriptionNotificationType.CREATE.equals(subscriptionNotify.getSubscriptionNotificationType())) { // handle your own business logic // e.g.：Save the user's payment information by linking the subscriptionRequestId with the user ID. System.out.println("receive subscription notify: " + JSON.toJSONString(subscriptionNotify)); return Result.builder().resultCode("SUCCESS").resultMessage("success.").resultStatus(ResultStatusType.S).build(); } } catch (Exception e) { return Result.builder().resultCode("FAIL").resultMessage("fail.").resultStatus(ResultStatusType.F).build(); } return Result.builder().resultCode("SYSTEM_ERROR").resultMessage("system error.").resultStatus(ResultStatusType.F).build(); } ``` 3. Respond to the notification result. You must respond to each notification request in the following fixed format, regardless of whether the payment is successful or not. Otherwise, Antom will resend the asynchronous notification. ```json { "result": { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } } ``` > **[INFO]** **Common questions** > > **​** > > **Q: Will Antom resend asynchronous notifications?** > > A: Yes. Notifications will be automatically resent within 24 hours under these circumstances: > > - If asynchronous notifications are not received due to network issues. > - If you receive an asynchronous notification from Antom but fail to respond in the format of [Return a receipt acknowledgment message](https://docs.antom.com/ac/tokenized/notifications.md#vQK5A) . > > Notifications can be resent up to 8 times, or until a correct response is received to stop delivery. Intervals are: 0 minute, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, 15 hours. > > ​ > > **Q: Is signature verification required for payment result notifications?** > > A: Yes. Antom will send a guaranteed callback request to you for signature verification. Please note that when assembling the message to be verified, it must be processed according to the standard format: ` ..` . Specifically, for the `` , the value must be taken directly rather than by parsing the JSON and reassembling. > > ​ > > **Q: If the initial payment fails, does the subscription become active?** > > A: No. If the initial payment for subscription creation fails, the subscription will not be activated. Antom will send a status notification via webhook with *subscriptionStatus* set to `TERMINATED` , indicating failed subscription creation. > > ​ > > **Q: What is the default expiry time for a subscription order creation？** > > A: > > - For APM payment types, the default subscription expiryTime is 80 minutes. > - For Card/ApplePay/GooglePay, the default subscription expiry time is 7 days. > > You can also specify the expiry time through the *subscriptionExpiryTime* field. #### Subscription renewal notifications {#DeF0l} After the subscription is created and activated successfully, Antom will automatically initiate renewal deductions based on your configured subscription rules and send corresponding payment result notifications via webhook to achieve periodic deductions. The timing and rules for triggering renewal payments are as follows: - **Trigger time:** Renewal deductions are triggered automatically 24 hours before the start of the next subscription cycle. You can determine the next deduction time by subtracting 24 hours from the *periodEndTime* parameter in the previous period's payment result notification. - **Cycle rules:** The renewal cycle and deduction frequency follow the *periodRule* set during subscription, such as daily, monthly, quarterly, or yearly deductions. | **First deduction time** **(**_paymentTime_** = **_periodStartTime_**)** | **Subscription cycle** | **Next deduction time** (**_paymentTime_**) | **Next period start time** (**_periodStartTime_**) | | --- | --- | --- | --- | | 2024-09-25T20:10:17+08:00 | To set the subscription cycle to 3 days, the following parameters need to be passed in: - *periodRule.periodCount* = `3` - *periodRule.periodType* = `DAY` | 2024-09-27T20:20:04+08:00 | 2024-09-28T20:10:17+08:00 | | 2024-09-25T20:10:17+08:00 | To set the subscription cycle to 1 week, the following parameters need to be passed in: - *periodRule.periodCount* = `1` - *periodRule.periodType* = `WEEK` | 2024-10-01T20:10:17+08:00 | 2024-10-02T20:10:17+08:00 | | 2024-09-25T20:10:17+08:00 | To set the subscription cycle to 1 month, the following parameters need to be passed in: - *periodRule.periodCount* = `1` - *periodRule.periodType* = `MONTH` | 2024-10-24T20:10:17+08:00 | 2024-10-25T20:10:17+08:00 | | 2024-09-25T20:10:17+08:00 | To set the subscription cycle to 1 year, the following parameters need to be passed in: - *periodRule.periodCount* = `1` - *periodRule.periodType* = `YEAR` | 2025-09-24T20:10:17+08:00 | 2025-09-25T20:10:17+08:00 | **Tab: Card payments, Google Pay, and Apple Pay** In card payment, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) scenarios, asynchronous notifications are typically categorized into the following cases: | **Common scenarios** | **First-time subscription payment** | **Subsequent recurring payments** | | --- | --- | --- | | authorization payment result notification | A notification is sent to inform you of the authorization result and the 3DS authentication result. | A notification is sent to inform you of the authorization result and the 3DS authentication result. | | Capture notification | If authorization payment is successful, a capture notification is sent. The capture result serves as the basis for shipment. | If authorization payment is successful, a capture notification is sent. The capture result serves as the basis for shipment. | | Subscription status notification | A notification is sent to inform you of the subscription creation result. | No notification. | | Current deduction result notification | A notification is sent to inform you of the current deduction result, amount, and validity period. | A notification is sent to inform you of the current deduction result, amount, and validity period. | The following is sample codes for asynchronous notifications in various scenarios: **Tab: Authorization payment result notification** The following is a sample code for the request body of authorization payment result notifications: ```json { "actualPaymentAmount": { "currency": "USD", "value": "1" }, "cardInfo": { "avsResultRaw": "U", "cardBrand": "VISA", "cardCategory": "CONSUMER", "cardNo": "************0550", "credentialTypeUsed": "PAN", "cvvResultRaw": "M", "funding": "PREPAID", "issuingCountry": "MY", "networkTransactionId": "2025100903100****37936376", "paymentMethodRegion": "GLOBAL", "threeDSResult": { "cavv": "mockCavv", "challengeCancel": "", "challenged": true, "dsTransactionId": "cce18b6e-b55e-40ff-814c-619b4598****", "eci": "02", "threeDSOffered": true, "threeDSVersion": "2.1.0", "threeDStransactionStatusReason": "" } }, "notifyType": "PAYMENT_RESULT", "paymentAmount": { "currency": "USD", "value": "1" }, "paymentCreateTime": "2025-10-08T19:11:20-07:00", "paymentId": "202510091940108001****89B0255128143", "paymentMethodType": "GOOGLEPAY", "paymentRequestId": "PAYMENT_202510****1050687_AUTO", "paymentResultInfo": { "avsResultRaw": "U", "cardBrand": "VISA", "cardCategory": "CONSUMER", "cardNo": "************0550", "credentialTypeUsed": "PAN", "cvvResultRaw": "M", "funding": "PREPAID", "issuingCountry": "MY", "networkTransactionId": "20251009031****b937936376", "paymentMethodRegion": "GLOBAL", "threeDSResult": { "cavv": "mockCavv", "challengeCancel": "", "challenged": true, "dsTransactionId": "cce18b6e-b55e-40ff-814c-619b4598****", "eci": "02", "threeDSOffered": true, "threeDSVersion": "2.1.0", "threeDStransactionStatusReason": "" } }, "paymentTime": "2025-10-08T19:11:38-07:00", "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ``` **Tab: Capture notification** The following is a sample code for the request body of capture notifications: ```json { "captureAmount": { "currency": "USD", "value": "1" }, "captureId": "2025100919401080****1889B0280060023", "captureRequestId": "PAYMENT_20251****01050687_AUTO", "captureTime": "2025-10-08T19:11:40-07:00", "notifyType": "CAPTURE_RESULT", "paymentId": "202510091940108****01889B0255128143", "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ``` **Tab: Subscription result notification** No notification. **Tab: Current deduction result notification** The following is a sample code for the request body of current deduction result notifications: ```json { "paymentAmount": { "currency": "USD", "value": "1" }, "notifyType": "PAYMENT_RESULT", "paymentCreateTime": "2025-10-08T19:10:51-07:00", "paymentId": "20251009194010****001889B0255128143", "paymentTime": "2025-10-08T19:11:40-07:00", "periodEndTime": "2025-08-02T19:15:29-07:00", "periodStartTime": "2025-07-26T19:15:29-07:00", "phaseNo": "1", "result": { "resultCode": "SUCCESS", "resultMessage": "success", "resultStatus": "S" }, "subscriptionId": "20251009190000000****000E0000032897", "subscriptionRequestId": "PAYMENT_202510****1050687_AUTO" } ``` Key parameter description: - *notifyType* : The notification type, with the value as `PAYMENT_RESULT` . - *phaseNo* : The installment number of the current subscription cycle. - *periodStartTime* : The start time of the current subscription cycle. - *periodEndTime* : The end time of the current subscription cycle. - *paymentAmount* : The amount deducted for each periodic payment. **Tab: APMs** In APM scenarios, asynchronous notifications are typically categorized into the following cases: | **Common scenarios** | **First-time subscription payment** | **Subsequent recurring payments** | | --- | --- | --- | | Payment result notification | A notification is sent to inform you of the payment result. | No notification. | | Subscription status notification | A notification is sent to inform you of the subscription creation result. | No notification. | | Current deduction result notification | A notification is sent to inform you of the current deduction result, amount, and validity period. | A notification is sent to inform you of the current deduction result, amount, and validity period. | The following is sample codes for asynchronous notifications in various scenarios: **Tab: Payment result notification** No notification. **Tab: Subscription status notification** No notification. **Tab: Current deduction result notification** The following is a sample code for the request body of current deduction result notifications: ```json { "paymentAmount": { "currency": "USD", "value": "1" }, "notifyType": "PAYMENT_RESULT", "paymentCreateTime": "2025-10-08T19:10:51-07:00", "paymentId": "20251009194010****001889B0255128143", "paymentTime": "2025-10-08T19:11:40-07:00", "periodEndTime": "2025-08-02T19:15:29-07:00", "periodStartTime": "2025-07-26T19:15:29-07:00", "phaseNo": "1", "result": { "resultCode": "SUCCESS", "resultMessage": "success", "resultStatus": "S" }, "subscriptionId": "20251009****00000000000E0000032897", "subscriptionRequestId": "PAYMENT_20251009101050687_AUTO" } ``` > **[INFO]** **Common questions** > > **​** > > **Q: Will a failed payment deduction terminate the subscription?** > A: If the initial payment for creating a subscription fails, the subscription will not be activated; if the subscription is already active but a subsequent recurring payment fails (e.g., due to insufficient balance), the subscription status remains active; if the subscription is not manually canceled, Antom will continue to attempt recurring payments in the next cycle. > > ​ > > **Q: Will a failed payment deduction trigger a notification, and will retries be attempted?** > A: A failed payment deduction will trigger a deduction failure notification. For card payments, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) subscriptions, Antom does not initiate retries. For APM subscriptions, Antom will perform multiple retries. If you wish to implement their own retry mechanism, please contact Antom Technical Support for customized solutions. > > ​ > > **Q: If the initial payment date is at the end of a month, such as February 28, March 31, or April 30, how is the next payment date determined?** > A: The subscription cycle logic is that the next deduction trggers based on the selected date. If the next cycle does not have the selected date, the system adjusts to the last day of that month. For example: > > - First cycle: Jan 28; Second cycle: Feb 28; Third cycle: Mar 28; Fourth cycle: Apr 28. > - First cycle: Jan 31; Second cycle: Feb 28; Third cycle: Mar 31; Fourth cycle: Apr 30. > - First cycle: Jan 30; Second cycle: Feb 28; Third cycle: Mar 30; Fourth cycle: Apr 30. > > ​ > > **Q: How are subsequent recurring deductions associated with the initial subscription contract?** > A: For recurring payment notifications, you can use the *subscriptionRequestId* or *subscriptionId* in the notification request to link to the initial subscription contract. For recurring payments of card payments, [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md), and [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), Antom additionally sends authorization result notifications and capture result notifications. The two kinds of notifications can be linked to the recurring payment notification via the *paymentId* and ultimately associated with the initial contract's *subscriptionId* . ## After subscription {#3XTVO} After completing the subscription, you can perform the following actions: ### Inquire payments **[Server-side]** {#z6Z7h} In addition to obtaining the buyer's payment result through the asynchronous notification, you can retrieve the corresponding payment result through the inquiry payments service . You can call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API and use the *paymentRequestId* from the payment session to check the payment status. The following code shows how to call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API: ```java 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 response: ```json { "actualPaymentAmount": { "currency": "USD", "value": "1" }, "customsDeclarationAmount": { "currency": "CNY", "value": "7" }, "paymentAmount": { "currency": "USD", "value": "1" }, "paymentId": "2025030519401080****8690281017336", "paymentMethodType": "ALIPAY_CN", "paymentRedirectUrl": "https://checkout.antom.com/checkout-page/pages/payment/index.html?sessionData=REDACTED_SESSION_DATA", "paymentRequestId": "PAYMENT_20250305220039086_AUTO", "paymentResultCode": "SUCCESS", "paymentResultMessage": "success.", "paymentStatus": "SUCCESS", "paymentTime": "2025-03-05T06:02:34-08:00", "pspCustomerInfo": { "pspName": "ALIPAY_CN" }, "result": { "resultCode": "SUCCESS", "resultMessage": "success.", "resultStatus": "S" } } ``` The table shows the possible values of *paymentStatus* returned in the response: | ***paymentStatus*** | **Message** | | --- | --- | | `SUCCESS` | Indicates that the payment is successful. | | `FAIL` | Indicates that the payment failed. | > **[INFO]** **Note** : When inquiring about the transaction, if the buyer does not submit the order, the `ORDER_NOT_EXIST` error code will be returned. This error is not returned if the order is submitted. ### Subscription trial {#n4oAa} Antom provides a subscription trial feature that allows buyers to experience a product or service for a limited time at no cost or at a discounted rate before officially purchasing a subscription plan. For more details, please refer to the [Subscription trial](https://docs.antom.com/ac/subscriptionpay/subscription_trial.md) . ### Subscription cancellation {#jcX2m} The subscription cancellation feature allows buyers to cancel their current subscription at any time when they no longer need to use the associated service. For more details, please refer to the [Subscription cancellation](https://docs.antom.com/ac/subscriptionpay/subscription_cancellation.md) . ### Cancel **[Server-side]** {#MouS5} For orders that have been successfully paid, if the buyer requests to cancel the order or refund on the same day, you can use Antom's cancel transaction capability to cancel or unfreeze the order status. Additionally, for orders that have not yet completed payment, you can also directly cancel them. For detailed integration solutions, please refer to [Cancel](https://docs.antom.com/ac/cashierpay/cancel.md) . ### Refund **[Server-side]** {#uHmJb} For orders that have been successfully paid, if you need to initiate a refund to the buyer, Antom offers the following two methods: - Your operation staff can manually process the refund directly on the [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login) . - You can initiate a refund by integrating with the [**refund**](https://docs.antom.com/ac/ams/refund_online.md) API. Antom's refund capabilities include: - Support for full refunds. - Support for partial multiple refunds, with the total amount of multiple refunds not exceeding the captured amount. For detailed integration solutions, please refer to [Refund](https://docs.antom.com/ac/cashierpay/refund.md) . ### Dispute **[Server-side]** {#KqxSD} When a buyer chooses to pay with a card, a dispute may occur. To learn more, see [Dispute](https://docs.antom.com/ac/cashierpay/dispute.md) . ### Reconciliation **[Server-side]** {#lLHCC} After the transaction is completed, use the financial reports provided by Antom for reconciliation. For more information on how to reconcile and the settlement rules of Antom, please refer to [Reconciliation](https://docs.antom.com/ac/cashierpay/reconcile.md) . ## Additonal content {#6YvKk} ### Specify a payment method {#3Tw77} You can specify payment methods on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome) through **Payments > Checkout page> Payment methods** . You can also pass the parameters in the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API to specify the display of payment methods on Checkout Page, the order of the payment method list, and the display of quick payments. > **[INFO]** **Note** : If you pass parameters through the API, the API values take priority. This feature offers you the following benefits: - Filter local payment methods based on your business region. - Sort your preferred payment methods. - Display the mainstream quick payments, such as [Alipay](https://docs.antom.com/ac/antomop/alipay_cn.md), [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), and [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md). **​** To specify the payment method, pass the following parameters in the *availablePaymentMethod* parameter of the [**createPaymentSession (One-time Payments)**](https://docs.antom.com/ac/ams/session_cashier.md) API: | **Parameter name** | **Required** | **Description** | | --- | --- | --- | | *paymentMethodTypeList* | No | List of payment methods available to the buyer. The list includes the following parameters: - *paymentMethodType* : The type of payment method included in the payment option. See [Enumeration values of payment methods](https://docs.antom.com/ac/pm/enumeration_values.md) for valid values. - *paymentMethodOrder* : The priority order you set for payment methods, represented by sequence numbers. The smaller the number, the higher the priority. If no sequence is set, Antom's default sorting will be used. - *expressCheckout* : Indicates whether the payment method selected by you is displayed as a quick payment method. Currently, only `ALIPAY_CN` , `APPLEPAY` , and `GOOGLEPAY` can be configured as quick payments. Valid values are: - `true` : The payment method is displayed as quick payment. - `false` : The payment method is not displayed as quick payment. | The following is a sample code for specifying the payment method: ```json { ... "availablePaymentMethod": { "paymentMethodTypeList": [ { "paymentMethodType": "ALIPAY_CN", "expressCheckout": true, "paymentMethodOrder": 0 }, { "paymentMethodType": "TNG", "expressCheckout": false, "paymentMethodOrder": 1 } ] } } ```