集成 Apple Pay 订阅支付
订阅支付是一种周期性自动扣款解决方案，可以帮助您完成周期性自动收款。仅需一次授权即可绑定支付账户享受持续的订阅服务，且支持动态调整订阅配置（如修改周期/金额、取消续订或终止服务等）。整个流程既便捷高效，又安全可靠。
本文主要针对 Apple Pay 支付方式进行集成说明。通过 Apple Pay 服务，买家可以使用存储在其 Apple Pay 账户中的信用卡或借记卡进行支付。采用 Native API 方式时，商户前端需直接集成 Apple Pay SDK，获取卡资产信息后调用 Antom 的 pay（单笔支付）接口发起支付。有关 Apple Pay SDK 的集成说明，请参见 Apple Pay on the Web 或 Apple Pay (Native)。
注意：采用 Native API 方式集成 Apple Pay 时，您需要有自己的 Apple 商家 ID 和证书，对于 Apple Pay Web 的集成方式，商户需在 Apple 侧完成域名验证。
用户体验
以下图片展示了集成 Apple Pay 进行支付的用户体验：
Web 端
Mobile 端
支付流程
您可以选择以下两种解密方式对获取的 ApplePayPaymentToken 进行解密，对应的支付流程也不同：
- 托管解密：由 Antom 负责证书管理和解密操作，您无需具备 PCI 资质。
- 商户解密：您自行管理证书并执行解密操作，您需具备相应的 PCI 资质。
以下图片展示了集成 Apple Pay 订阅支付的流程：
托管解密
商户解密
首次订阅
后续扣款
以下为 Antom 托管解密 ApplePayPaymentToken 的首次订阅支付流程示意图：
以下为 Antom 托管解密 ApplePayPaymentToken 的后续扣款的支付流程示意图：
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
集成步骤
请按照以下步骤开始集成：
- 获取 ApplePayPaymentToken
- 创建订阅支付请求
- 授权结果通知
- 请款并获取请款通知
- 获取订阅通知
步骤 1：获取 ApplePayPaymentToken
当买家在通过 Touch ID, Face ID, 或者 passcode 完成 Apple Pay 支付授权后，前端在 Apple Pay 授权事件中获取 ApplePayPaymentToken，详情请参见 或 。在您获取到 ApplePayPaymentToken 以后，您可以选择 Antom 托管解密，从而调用 pay（单笔支付）接口来发起授权订阅支付请求。
步骤 2：创建订阅支付请求 服务端
在您集成 Apple Pay SDK 并在 Apple Pay 注册 merchant identifier 后，请使用您在 Apple Pay 的配置进行交互。关于 Apple Pay 的集成请参考 Apple Pay 官方文档。
您获取到 ApplePayPaymentToken 并托管给 Antom 解密后，请使用 Antom 卡的授权支付能力发起支付。您可以通过 pay（单笔支付）的 paymentMethod.paymentMethodMetaData.applePayConfiguration 参数传入解密的 ApplePayPaymentToken。
使用托管解密 ApplePayPaymentToken 前您需先完成证书交换操作。根据 Antom 的标准生成 Payment Processing Certificate 并发给 Antom 配置。步骤如下：
- 商户提供生成 CSR 时需要指定 DN 值给 Antom CN (Common Name) 公共名称，通常用来标识组织名称或者项目名称。
- L (Locality Name) 城市/地区
- ST (State or Province Name) 州/省
- O (Organization Name) 组织名称，通常是公司正式名
- （可选）OU (Organizational Unit Name) 组织部门
- C (Country Name) 国家代码
- Antom 生成 CSR 证书后交由商户，商户在 Apple 开发者中心上传 CSR，并下载 CER 后缀的的 Payment Processing Certificate 证书后交由 Antom。
- Antom 拿到 CER 文件后完成配置。
如您有任何疑问，请联系 Antom SA 获取更多支持。
注意：使用该集成方式请自行关注 CER 证书失效时间，并至少在证书失效前一个月邮件联系 Antom 技术支持（TechnicalService@Antom.com）完成证书更换。
public static void payByApplePayServer2Server() {
AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
// 替换为您的 paymentRequestId
String paymentRequestId = UUID.randomUUID().toString();
alipayPayRequest.setPaymentRequestId(paymentRequestId);
// 设置金额
Amount amount = Amount.builder().currency("SGD").value("4200").build();
alipayPayRequest.setPaymentAmount(amount);
// 设置支付方式
PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("APPLEPAY").build();
alipayPayRequest.setPaymentMethod(paymentMethod);
// 设置ApplePay的相关参数 --托管解密
Map<String, String> applePayToken = new HashMap<String, String>();
applePayToken.put("applePayToken", "{"paymentData":{....}");
paymentMethodMetaData.put("applePayConfiguration", applePayToken);
paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);
// 替换为您的 orderId
String orderId = UUID.randomUUID().toString();
// 设置买家信息
Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();
// 设置订单信息
Order order = Order.builder().referenceOrderId(orderId)
.orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
alipayPayRequest.setOrder(order);
// 设置设备环境信息
Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("1.2.3.4").build();
alipayPayRequest.setEnv(env);
// 设置订阅信息
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);
// 替换为您的通知地址
alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");
// 替换为您的跳转地址
alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");
// 支付
AlipayPayResponse alipayPayResponse = null;
try {
alipayPayResponse = CLIENT.execute(alipayPayRequest);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// 处理错误情况
}
}以下代码显示了请求报文的示例：
{
"subscriptionInfo": {
"subscriptionDescription": "Subscription test",
"subscriptionStartTime": "2025-02-15T14:55:16+08:00",
"subscriptionNotifyUrl": "https://your.example.com/subscriptionNotify",
"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
}
}首次订阅
后续扣款
以下为商户解密 ApplePayPaymentToken 的首次订阅支付流程示意图：
以下为商户解密 ApplePayPaymentToken 的后续扣款的支付流程示意图：
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
集成步骤
请按照以下步骤开始集成：
- 获取 ApplePayPaymentToken
- 创建订阅支付请求
- 授权结果通知
- 请款并获取请款通知
- 获取订阅通知
步骤 1：获取 ApplePayPaymentToken
当买家在通过 Touch ID, Face ID, 或者 passcode 完成 Apple Pay 支付授权后，前端在 Apple Pay 授权事件中获取 ApplePayPaymentToken，详情请参见 或 。在您获取到 ApplePayPaymentToken 以后，您可以选择商户自行解密，从而调用 pay（单笔支付）接口来发起授权订阅支付请求。
步骤 2：创建订阅支付请求 服务端
在您集成 Apple Pay SDK 并在 Apple Pay 注册 merchant identifier 后，请使用您在 Apple Pay 的配置进行交互。关于 Apple Pay 的集成说明请参见 Web 或者 iOS 。
您获取到 ApplePayPaymentToken 后，请根据 ApplePay 的 Payment token format reference 进行解密获取 DPAN 信息。您获取到 DPAN 信息后，请使用 Antom 卡的授权支付能力发起支付。
注意：使用该方式解密需要您具备 PCI 资质，并在 Apple Pay 后台上传 PCI 证明。
请关注以下重点授权支付请求参数：
public static void payByApplePayServer2Server() {
AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
// 设置订阅信息
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");
// 设置订阅周期规则
PeriodRule periodRule = new PeriodRule();
periodRule.setPeriodType("MONTH");
periodRule.setPeriodCount(1);
subscriptionInfo.setPeriodRule(periodRule);
alipayPayRequest.setSubscriptionInfo(subscriptionInfo);
// 替换为您的 paymentRequestId
String paymentRequestId = UUID.randomUUID().toString();
alipayPayRequest.setPaymentRequestId(paymentRequestId);
// 设置金额
Amount amount = Amount.builder().currency("HKD").value("30000").build();
alipayPayRequest.setPaymentAmount(amount);
// 设置支付方式 - APPLEPAY（商户解密）
PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("APPLEPAY").build();
// 设置商户解密相关参数
Map<String, Object> paymentMethodMetaData = new HashMap<>();
paymentMethodMetaData.put("cardNo", "11111111111111");
paymentMethodMetaData.put("expiryYear", "30");
paymentMethodMetaData.put("expiryMonth", "12");
// 设置 MPI 数据
MpiData mpiData = new MpiData();
mpiData.setCavv("applePay cryptogram");
mpiData.setEci("eci indicator");
paymentMethodMetaData.put("mpiData", mpiData);
paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);
alipayPayRequest.setPaymentMethod(paymentMethod);
// 替换为您的 orderId
String orderId = UUID.randomUUID().toString();
// 设置买家信息
Buyer buyer = Buyer.builder()
.buyerEmail("gaga@gaga.com")
.buyerPhoneNo("123456789")
.referenceBuyerId("88888888")
.build();
// 设置订单信息
Order order = Order.builder()
.referenceOrderId(orderId)
.orderDescription("《Bad Romance》-Lady Gaga")
.orderAmount(amount)
.buyer(buyer)
.build();
alipayPayRequest.setOrder(order);
// 设置设备环境信息
Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("112.80.248.78").build();
alipayPayRequest.setEnv(env);
// 结算策略（商户合同币种）
SettlementStrategy settlementStrategy = SettlementStrategy.builder().settlementCurrency("USD").build();
alipayPayRequest.setSettlementStrategy(settlementStrategy);
// 设置授权请款模式
PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
alipayPayRequest.setPaymentFactor(paymentFactor);
// 替换为您的通知地址
alipayPayRequest.setPaymentNotifyUrl("https://kademo.intlalipay.cn/payments/notifySuccess");
// 替换为您的跳转地址
alipayPayRequest.setPaymentRedirectUrl("https://kademo.intlalipay.cn/melitigo/Test_114.html");
// 支付
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);
// 处理错误情况
}
}以下代码显示了请求报文的示例：
{
"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
}
}步骤 3：授权结果通知 服务端
步骤 4：请款并获取请款通知 服务端
注意：
- 只有授权支付成功才会触发请款。
- 您需要根据请款结果来决定是否发货。
授权支付成功后，Antom 默认自动为您请款，也支持您手动发起请款。同时，Antom 会使用 notifyCapture（单笔支付）将请款结果通知发送给您，您也可以通过主动查询来获取请款结果。您需要根据请款结果来决定是否发货，具体操作请参阅请款。
步骤 5：获取订阅通知 服务端
订阅关系生效后，Antom 会为您发送以下通知：
订阅后操作
完成订阅支付后，您可对交易进行以下操作：
查询订阅相关信息 服务端
订阅确认后，您可以查询以下订阅信息：
- 查询订阅列表：您可以通过 inquireSubscriptionList 接口查询符合特定筛选条件的订阅列表。
- 查询订阅详情：您可以使用 subscriptionId 调用 inquireSubscription 接口来获取订阅详情。
- 查询订阅交易信息：您可以使用 subscriptionId 调用 inquireSubscriptionPayment 接口来获取订阅交易的列表信息。
订阅试用 服务端
终止订阅 服务端
取消交易 服务端
对于支付成功后的订单，如买家在当天内申请取消订单或退款，您可以通过 Antom 提供的取消交易能力将订单状态取消或解冻。此外，对于尚未完成支付的订单，您也可以直接进行取消，具体的集成方案见取消交易文档。