Antom, leading provider of tailored payment solutions
Contact Us
Log In

Accept recurring payments with Apple Pay

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.
This document provides integration instructions for Apple Pay. Through the Apple Pay service, buyers can make payments using the credit or debit cards stored in their Apple Pay accounts. When using the Native API method, the merchant frontend needs to directly integrate the Apple Pay SDK. After obtaining the card asset information, call Antom’s pay (One-time Payments) API to initiate the payment. For details on integrating the Apple Pay SDK, refer to Apple Pay on the Web or Apple Pay (Native).
Note: When integrating Apple Pay using the Native API method, you need to have your own Apple merchant identifier and certificate. For the Apple Pay Web integration method, merchants must complete domain verification on Apple’s side.

User experience

The following figures demonstrate the user experience of paying with Apple Pay:
Web
Mobile

Payment flow

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:
Hosted decryption
First-time subscription
The following illustrates the payment flow for the initial subscription payment process using Antom-decrypted ApplePayPaymentToken:
Subsequent deductions
The following illustrates the payment flow for the subsequent periodic deductions process using Antom-decrypted ApplePayPaymentToken:

Integration preparations

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.

Integration Steps

Follow these steps to start the integration:
  1. Obtain ApplePayPaymentToken
  2. Create a subscription payment request
  3. Obtain the authorization result
  4. Capture and recieve the capture notification
  5. 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 toonpaymentauthorized (Web)or paymentAuthorizationViewController:didAuthorizePayment:handler: (Native). 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 integrating the Apple Pay SDK and registering a merchant identifier with Apple Pay, use your Apple Pay configuration for interaction. For details on Apple Pay integration, please refer to Apple Pay.
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:
  1. 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
  1. 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.
  2. 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.
Follow Step 2: Create a subscription payment request to call the pay (One-time Payments) API and submit the payment request. You need to pass in the basic parameters, order parameters, and device parameters in the payment request. While you do not need to pass in card payment parameters, you need to pass in the following parameters:
Parameter name
Required
Description
paymentMethod.paymentMethodType
Yes
Payment method enumeration values. For Apple Pay, pass in APPLEPAY.
paymentMethod.paymentMethodMetaData.applePayConfiguration.applePayToken
Yes
Pass in ApplePayPaymentToken you obtained.
paymentMethod.paymentMethodMetaData.is3DSAuthentication
No
In Apple Pay scenarios, set this to false or omit to avoid re-verifying the buyer’s identity.
For more information about the parameters used to initiate an authorized payment, refer to Step 2: Create a subscription payment request.
The following sample code shows how to call the pay (One-time Payments) API:
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
    }
}
Merchant decryption
First-time subscription
The following illustrates the payment flow for the initial subscription payment process using merchant-decrypted ApplePayPaymentToken:
Subsequent deductions
The following illustrates the payment flow for the subsequent periodic deductions process using merchant-decrypted ApplePayPaymentToken:

Integration preparations

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.

Integration Steps

Follow these steps to start the integration:
  1. Obtain ApplePayPaymentToken
  2. Create a subscription payment request
  3. Obtain the authorization result
  4. Capture and recieve the capture notification
  5. 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 toonpaymentauthorized (Web)or paymentAuthorizationViewController:didAuthorizePayment:handler: (Native). 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:
Parameter name
Required
Description
paymentMethod.paymentMethodType
Yes
Payment method enumeration values. For Apple Pay, pass inAPPLEPAY.
paymentMethod.paymentMethodMetaData.cardNo
Yes
Pass in the value of the applicationPrimaryAccountNumber parameter from the obtained DPAN information.
paymentMethod.paymentMethodMetaData.expiryMonth
Yes
Pass in the month value of the applicationExpirationDate parameter from the obtained DPAN information.
paymentMethod.paymentMethodMetaData.expiryYear
Yes
Pass in the year value of the applicationExpirationDate parameter from the obtained DPAN information.
paymentMethod.paymentMethodMetaData.mpiData.cavv
Yes
Pass in the value of the paymentData.onlinePaymentCryptogram parameter from the obtained DPAN information.
paymentMethod.paymentMethodMetaData.mpiData.eci
Yes
Pass in the value of the paymentData.eciIndicator parameter from the obtained DPAN information.
For more information on the parameters for initiating an authorized subscription payment request, please refer to Step 2: Create a subscription payment request.
The following sample code shows how to call the pay (One-time Payments) API:
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:
For more details, refer to Step 6: Receive subscription notifications.

After subscription

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.

Cancellation
Server-side

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.

Refund
Server-side

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.