Subscription payment is a recurring automatic payment solution that enables merchants to collect payments periodically. With a one-time authorization, buyers can link their payment accounts to enjoy continuous subscription services, while supporting dynamic adjustments to subscription configurations (such as modifying cycle/amount, canceling renewal, or terminating services, etc.). The entire process is both efficient and secure.
The following figures demonstrate the user experience of paying with Apple Pay: You can choose one of the following two decryption methods to decrypt the obtained ApplePayPaymentToken, and the corresponding payment processes differ.
- Hosted decryption: Antom manages certificates and performs decryption on your behalf, so you do not need to be PCI-qualified.
- Merchant decryption: You manage your own certificates and perform decryption operations yourself, and this mode requires that you are PCI-qualified.
Note: For more information about PCI DSS compliance requirements, see PCI DSS standard. The following illustrates the payment flow of accepting recurring payments with Apple Pay: The following illustrates the payment flow for the initial subscription payment process using Antom-decrypted ApplePayPaymentToken:
The following illustrates the payment flow for the subsequent periodic deductions process using Antom-decrypted ApplePayPaymentToken:
Before you start integrating, read the Integration guide and API Overview 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.
Follow these steps to start the integration:
- Obtain ApplePayPaymentToken
- Create a subscription payment request
- Obtain the authorization result
- Capture and recieve the capture notification
- Recieve subscription notifications
Step 1: Obtain ApplePayPaymentToken
When the buyer completes Apple Pay payment authorization using Touch ID, Face ID, or a passcode, the frontend obtains ApplePayPaymentToken in the Apple Pay authorization event. For details, refer toor . After you obtain ApplePayPaymentToken, you can choose the Antom-hosted decryption method to decrypt the token and call the pay (One-time Payments) API to initiate an authorized payment request. Step 2: Create a subscription payment request
Server-side
After you obtain ApplePayPaymentToken and delegate its decryption to Antom, use Antom’s card authorization payment capability to initiate the payment. You can pass the decrypted ApplePayPaymentToken through the paymentMethod.paymentMethodMetaData.applePayConfiguration parameter in the pay (One-time Payments) API. Before using hosted decryption for ApplePayPaymentToken, you need to complete the certificate exchange process. Generate a Payment Processing Certificate according to Antom’s standard and provide it to Antom for configuration. The steps are as follows:
- When generating the CSR, you need to specify the DN values to Antom CN (Common Name). The CN (Common Name) is typically used to identify the organization name or project name.
- L: Locality name
- ST: State or province name
- O: Organization name, typically the company’s legal name.
- (Optional) OU: Organizational unit name
- C: Country name
- Antom generates the CSR certificate and delivers it to you. You then upload the CSR to Apple Developer, download the Payment Processing Certificate with .CER suffix, and then send it to Antom.
- Antom completes the configuration after obtaining the CER file.
If you have any questions, contact Antom SA for support.
Note: When using this integration method, pay attention to the expiration time of the CER certificate, and contact Antom Technical Support (TechnicalService@antom.com) at least one month before the certificate expires to complete the certificate renewal. public static void payByApplePayServer2Server() {
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 paymentMethod
PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("APPLEPAY").build();
alipayPayRequest.setPaymentMethod(paymentMethod);
// set ApplePay related parameters-hosted decryption
Map<String, String> applePayToken = new HashMap<String, String>();
applePayToken.put("applePayToken", "{"paymentData":{....}");
paymentMethodMetaData.put("applePayConfiguration", applePayToken);
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 env info
Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("1.2.3.4").build();
alipayPayRequest.setEnv(env);
// set subscription info
SubscriptionInfo subscriptionInfo = new SubscriptionInfo();
subscriptionInfo.setSubscriptionDescription("Subscription test");
subscriptionInfo.setSubscriptionStartTime("2025-02-15T14:55:16+08:00");
subscriptionInfo.setSubscriptionNotifyUrl("https://www.your.notifyUrl.com");
PeriodRule periodRule = new PeriodRule();
periodRule.setPeriodType("MONTH");
periodRule.setPeriodCount(1);
subscriptionInfo.setPeriodRule(periodRule);
alipayPayRequest.setSubscriptionInfo(subscriptionInfo);
// replace with your notify url
alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");
// replace with your redirect url
alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");
// pay
AlipayPayResponse alipayPayResponse = null;
try {
alipayPayResponse = CLIENT.execute(alipayPayRequest);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// handle error condition
}
}
The following shows the sample code of a request:
{
"subscriptionInfo": {
"subscriptionDescription": "Subscription test",
"subscriptionStartTime": "2025-02-15T14:55:16+08:00",
"subscriptionNotifyUrl": "https://www.your.notifyUrl.com",
"periodRule": {
"periodType": "MONTH",
"periodCount": 1
}
},
"order": {
"orderAmount": {
"currency": "HKD",
"value": "30000"
},
"orderDescription": "《Bad Romance》-Lady Gaga",
"referenceOrderId": "ORDER_2023120811154****",
"buyer": {
"buyerEmail": "gaga@gaga.com",
"buyerPhoneNo": "123456789",
"referenceBuyerId": "88888888"
}
},
"env": {
"terminalType": "WEB",
"clientIp": "112.80.248.78"
},
"paymentAmount": {
"currency": "HKD",
"value": "30000"
},
"paymentMethod": {
"paymentMethodType": "APPLEPAY",
"paymentMethodMetaData": {
"applePayConfiguration": {
"applePayToken": "{"paymentData":{"data":"a9+mMMEXE5iIL***","signature":"MIAGCSqGSIb***","header":{"publicKeyHash":"Ch94ASjb4+dAeBnbQh***","ephemeralPublicKey":"MFkwEw****","transactionId":"940bf1714c***"},"version":"EC_v1"},"paymentMethod":{"displayName":"Visa0869","network":"Visa","type":"debit"},"transactionIdentifier":"940bf17****"}"
}
}
},
"settlementStrategy": {
"settlementCurrency": "USD"
},
"paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
"paymentRequestId": "PAY_20231204811154444****",
"productCode": "CASHIER_PAYMENT",
"paymentFactor": {
"isAuthorization": true
}
}
The following illustrates the payment flow for the initial subscription payment process using merchant-decrypted ApplePayPaymentToken:
The following illustrates the payment flow for the subsequent periodic deductions process using merchant-decrypted ApplePayPaymentToken:
Before you start integrating, read the Integration guide and API Overview 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.
Follow these steps to start the integration:
- Obtain ApplePayPaymentToken
- Create a subscription payment request
- Obtain the authorization result
- Capture and recieve the capture notification
- Recieve subscription notifications
Step 1: Obtain ApplePayPaymentToken
When the buyer completes Apple Pay payment authorization using Touch ID, Face ID, or a passcode, the frontend obtains ApplePayPaymentToken in the Apple Pay authorization event. For details, refer toor . After you obtain ApplePayPaymentToken, you can choose the merchant decryption method to decrypt the token and call the pay (One-time Payments) API to initiate an authorized payment request. Step 2: Create a subscription payment request
Server-side
After you have integrated the Apple Pay SDK and registered a merchant identifier with Apple Pay, please use your Apple Pay configuration for interactions. For detailed instructions on Apple Pay integration, please refer to the documentation for Web or iOS. After you obtain ApplePayPaymentToken, decrypt it according to Apple Pay’s Payment token format reference to retrieve the DPAN information. Once you have obtained the DPAN information, use Antom’s card authorized payment capability to initiate the payment. Note: Using this mode requires that you are PCI-qualified and you have uploaded the PCI proof to the Apple Pay backend. The following are key parameters for initiating a authorized payment request:
public static void payByApplePayServer2Server() {
AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
// Set subscription information
SubscriptionInfo subscriptionInfo = new SubscriptionInfo();
subscriptionInfo.setSubscriptionDescription("Subscription test");
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssXXX");
subscriptionInfo.setSubscriptionStartTime(ZonedDateTime.now().format(formatter));
subscriptionInfo.setSubscriptionNotifyUrl("https://www.your.SubscriptionNotifyUrl.com");
// Set subscription period rule
PeriodRule periodRule = new PeriodRule();
periodRule.setPeriodType("MONTH");
periodRule.setPeriodCount(1);
subscriptionInfo.setPeriodRule(periodRule);
alipayPayRequest.setSubscriptionInfo(subscriptionInfo);
// Replace with your paymentRequestId
String paymentRequestId = UUID.randomUUID().toString();
alipayPayRequest.setPaymentRequestId(paymentRequestId);
// Set amount
Amount amount = Amount.builder().currency("HKD").value("30000").build();
alipayPayRequest.setPaymentAmount(amount);
// Set payment method - APPLEPAY (merchant decryption)
PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("APPLEPAY").build();
// Set merchant decryption related parameters
Map<String, Object> paymentMethodMetaData = new HashMap<>();
paymentMethodMetaData.put("cardNo", "11111111111111");
paymentMethodMetaData.put("expiryYear", "30");
paymentMethodMetaData.put("expiryMonth", "12");
// Set MpiData information
MpiData mpiData = new MpiData();
mpiData.setCavv("applePay cryptogram");
mpiData.setEci("eci indicator");
paymentMethodMetaData.put("mpiData", mpiData);
paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);
alipayPayRequest.setPaymentMethod(paymentMethod);
// Replace with your orderId
String orderId = UUID.randomUUID().toString();
// Set buyer information
Buyer buyer = Buyer.builder()
.buyerEmail("gaga@gaga.com")
.buyerPhoneNo("123456789")
.referenceBuyerId("88888888")
.build();
// Set order information
Order order = Order.builder()
.referenceOrderId(orderId)
.orderDescription("《Bad Romance》-Lady Gaga")
.orderAmount(amount)
.buyer(buyer)
.build();
alipayPayRequest.setOrder(order);
// Set device environment information
Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("112.80.248.78").build();
alipayPayRequest.setEnv(env);
// Settlement strategy (merchant contract currency)
SettlementStrategy settlementStrategy = SettlementStrategy.builder().settlementCurrency("USD").build();
alipayPayRequest.setSettlementStrategy(settlementStrategy);
// Set authorization and capture mode
PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
alipayPayRequest.setPaymentFactor(paymentFactor);
// Replace with your notification URL
alipayPayRequest.setPaymentNotifyUrl("https://kademo.intlalipay.cn/payments/notifySuccess");
// Replace with your redirect URL
alipayPayRequest.setPaymentRedirectUrl("https://kademo.intlalipay.cn/melitigo/Test_114.html");
// Execute payment
AlipayPayResponse alipayPayResponse = null;
try {
alipayPayResponse = CLIENT.execute(alipayPayRequest);
System.out.println("Payment successful: " + alipayPayResponse);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
System.out.println("Payment failed: " + errorMsg);
// Handle error case
}
}
The following shows the sample code of a request:
{
"subscriptionInfo": {
"subscriptionDescription": "Subscription test",
"subscriptionStartTime": "2025-02-15T14:55:16+08:00",
"subscriptionNotifyUrl": "https://www.your.SubscriptionNotifyUrl.com",
"periodRule": {
"periodType": "MONTH",
"periodCount": 1
}
},
"order": {
"orderAmount": {
"currency": "HKD",
"value": "30000"
},
"orderDescription": "《Bad Romance》-Lady Gaga",
"referenceOrderId": "ORDER_2023120811154****",
"buyer": {
"buyerEmail": "gaga@gaga.com",
"buyerPhoneNo": "123456789",
"referenceBuyerId": "88888888"
}
},
"env": {
"terminalType": "WEB",
"clientIp": "112.80.248.78"
},
"paymentAmount": {
"currency": "HKD",
"value": "30000"
},
"paymentMethod": {
"paymentMethodType": "APPLEPAY",
"paymentMethod": {
"paymentMethodMetaData": {
"is3DSAuthentication": false,
"isCardOnFile": false,
"enableAuthenticationUpgrade": false,
"cardholderName": {
"fullName": "**************"
},
"expiryMonth": "**",
"expiryYear": "**",
"cardNo": "****************",
"mpiData": {
"cavv": "ACZUcKxseEODAk/CjaCeGgADFA==",
"eci": "02"
}
},
"settlementStrategy": {
"settlementCurrency": "USD"
},
"paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
"paymentRequestId": "PAY_20231204811154444****",
"productCode": "CASHIER_PAYMENT",
"paymentFactor": {
"isAuthorization": true
}
}
Step 3: Obtain the authorization result
Server-side
After the buyer completes payment or the payment times out, you can obtain the payment result either by receiving asynchronous notifications from Antom or by proactively querying the result. For detailed steps, refer to Step 4: Obtain the authorization result. Step 4: Capture and recieve the capture notification
Server-side
Note:
- Only successful authorized payments will trigger capture.
- You need to decide whether to ship goods based on the capture result.
After successful authorization, Antom will automatically initiate capture for you, or you can choose to initiate capture manually. Meanwhile, Antom will send the capture result notification to you via the notifyCapture (One-time Payments) API, or you can proactively query to obtain the capture result. You should decide whether to ship goods based on the capture result. For specific operations, refer to Capture. Step 5: Recieve subscription notifications
Server-side
After the subscription relationship takes effect, Antom will send the following notifications:
After completing the subscription, you can perform the following actions:
Inquire subscription information
Server-side
After your subscription is confirmed, you can query the following subscription information:
Subscription trial
Server-side
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. Subscription cancellation
Server-side
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. For successful payments, if the buyer requests cancellation or a refund on the same day, you can use Antom’s cancellation capability to cancel the order or release funds. Orders not yet completed can also be cancelled directly. For details, refer to Cancel. To learn about Antom refund rules and how to initiate a refund for a successful transaction, see Refund for more information. Reconciliation
Server-side
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, refer to Reconciliation. 
