集成 Apple Pay 支付
通过 Apple Pay 服务，买家可以使用存储在其 Apple Pay 账户中的信用卡或借记卡进行支付。借助 Antom Checkout Page，您无需额外集成 Apple Pay 的 SDK，Checkout Page 将会为您加载 Apple Pay 服务，并支持将 Apple Pay 配置为极速支付方式。
用户体验
集成准备
- Antom 为您提供预置的 Apple Pay 商户认证，方便您快速集成。请按照以下步骤进行认证：
- 将您用于接收支付的服务器域名
DOMAIN_NAME提供给 Antom 技术专员。 - 联系 Antom 技术专员获取 Apple Pay 的域名验证文件，并将该文件放置在以下服务器目录中：
https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association在您开始集成前，请阅读集成指南及接口概述文档，了解服务端接口的集成步骤及调用接口的注意事项，并确保已完成以下预配置：
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
- 参阅 Web/WAP 端集成 SDK 资源包文档来集成客户端 SDK 资源包，并注意使用最新或不低于 1.41.0 版本的 SDK。
集成步骤
请按照以下步骤开始集成：
- 创建支付会话
- 嵌入 Antom Checkout Page
- 获取支付结果
- 发起请款
步骤 1：创建支付会话
您可以调用 支付会话创建（收银台）接口并传入订单信息，创建支付会话后跳转至 Antom Checkout Page。
以下是请求参数重点字段：
类型 | 字段 | 是否必需 | 描述 |
基础字段 | productCode | 是 | 此场景下该字段的值固定为 |
productScene | 是 | 此场景下该字段的值固定为 | |
paymentRequestId | 是 | 商户为识别支付请求而分配的专属 ID。 | |
paymentAmount | 是 | 商户请求以订单币种收取的支付金额。 | |
paymentRedirectUrl | 是 | 支付完成后买家被重定向到的商户页面链接。 | |
paymentNotifyUrl | 否 | 支付结果通知地址，可通过接口指定或在 Antom Dashboard 上设置固定值。 | |
settlementStrategy | 否 | 支付请求的结算策略。如果您签署了多个结算币种，需在接口中指 settlementCurrency。 | |
locale | 否 | 商户指定的 Antom Checkout Page 展示语言。如果该字段为空或设置为自动，则将使用浏览器的默认语言设置，通常为英文。 | |
paymentFactor.isAuthorization | 否 | 表示支付场景是否为授权场景。有效值为：
| |
订单字段 | order.orderAmount | 是 | 商户端订单金额。 |
order.referenceOrderId | 是 | 商户端订单号。 | |
order.orderDescription | 是 | 商户端订单描述。 | |
order.buyer | 是 | 商户端买家信息。至少需要提供以下三者其中一个信息：
| |
设置 Apple Pay 的相关参数 | availablePaymentMethod.paymentMethodMetaData.applePayConfiguration | 否 | 在 Checkout Page 场景下，该参数建议使用缺省值。
|
| 指定 Apple Pay 为极速支付方式 | availablePaymentMethod.paymentMethodTypeList.expressCheckout | 否 | 您可以通过设置该参数的值为 |
以上参数是创建支付会话的基本参数，完整参数和特定支付方式的额外要求请参考 支付会话创建（收银台）。
以下代码展示了如何调用 支付会话创建（收银台）接口：
/**
* show how to card payment Session(need to finish payment by Antom SDK)
*/
public static void executePaymentSessionCreateWithApplePay() {
AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
alipayPaymentSessionRequest.setProductScene("CHECKOUT_PAYMENT");
// 替换为您的 paymentRequestId
String paymentRequestId = UUID.randomUUID().toString();
alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);
// 设置金额
Amount amount = Amount.builder().value("4200").currency("SGD").build();
alipayPaymentSessionRequest.setPaymentAmount(amount);
// AvailablePaymentMethod
AvailablePaymentMethod available = new AvailablePaymentMethod();
List<PaymentMethodTypeItem> list = new ArrayList<>();
PaymentMethodTypeItem item = new PaymentMethodTypeItem();
item.setPaymentMethodType("APPLEPAY");
item.setPaymentMethodOrder(0);
item.setExpressCheckout(true);
list.add(item);
available.setPaymentMethodTypeList(list);
alipayPaymentSessionRequest.setAvailablePaymentMethod(available);
// 替换为您的 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();
alipayPaymentSessionRequest.setOrder(order);
// 替换为您的通知地址
alipayPaymentSessionRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com");
// 替换为您的跳转地址
alipayPaymentSessionRequest.setPaymentRedirectUrl("http://www.yourRedirectUrl.com");
// 支付
AlipayPaymentSessionResponse alipayPaymentSessionResponse = null;
try {
alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
System.out.println(JSONObject.toJSON(alipayPaymentSessionResponse));
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// 处理错误情况
}
}以下代码展示了一个请求报文的示例：
{
"order": {
"buyer": {
"referenceBuyerId": "yourBuyerId"
},
"goods": [
{
"goodsBrand": "Antom Brand",
"goodsCategory": "outdoor goods/bag",
"goodsImageUrl": "https://mdn.alipayobjects.com/portal_pdqp4x/afts/file/A*H8M9RrxlArAAAAAAAAAAAAAAAQAAAQ",
"goodsName": "Classic Woman Bag",
"goodsQuantity": "1",
"goodsSkuName": "Black",
"goodsUnitAmount": {
"currency": "SGD",
"value": "6000"
},
"goodsUrl": "https://yourGoodsUrl",
"referenceGoodsId": "yourGoodsId"
}
],
"orderAmount": {
"currency": "SGD",
"value": "6000"
},
"orderDescription": "antom ckp testing order",
"referenceOrderId": "c3df9b82-ff67-424b-880b-06c3615b46ea"
},
"paymentAmount": {
"currency": "SGD",
"value": "6000"
},
"availablePaymentMethod": {
"paymentMethodTypeList": [
{
"paymentMethodType": "APPLEPAY",
"expressCheckout": true,
"paymentMethodOrder": 0
}
]
},
"paymentNotifyUrl": "http://www.yourNotifyUrl.com/payment/receiveNotify",
"paymentRedirectUrl": "http://localhost:8080/index.html?paymentRequestId=597795b7-c812-4132-bd7d-c55914eefdcb",
"paymentRequestId": "597795b7-c812-4132-bd7d-c55914eefdcb",
"productCode": "CASHIER_PAYMENT",
"productScene": "CHECKOUT_PAYMENT"
}以下代码展示了一个响应的示例，其中包含以下参数：
- paymentSessionData：将返回给前端的支付会话数据。
- paymentSessionExpiryTime：支付会话的过期时间。
- normalUrl: Checkout Page 的跳转链接。（在嵌入式场景下，可以忽略此字段。）
{
"normalUrl": "https://checkout.antom.com/checkout-page/pages/payment/index.html?sessionData=1iwX2rH5kXnUGT5372d0kHD7PwcgPmRSMgAsvKs8hqRkqobbtWbep59PU2eO5w72h%2B%2XXXX",
"paymentSessionData": "1iwX2rH5kXnUGT5372d0kHD7PwcgPmRSMgAsvKs8hqRkqobbtWbep59PU2eO5w72h+/c278B+P+nDVNzrQySQQ==&&SG&&188&&eyJleHRlbmRJbmZvIjoie1wiT1BFTl9NVUxUSXXXX",
"paymentSessionExpiryTime": "2025-03-19T16:21:06+08:00",
"paymentSessionId": "1iwX2rH5kXnUGT5372d0kHD7PwcgPmRSMgAsvKs8hqSln4WiVZXXXX",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}下表展示了请求报文中 result.resultStatus 字段可能返回的值，请您根据指引进行处理：
result.resultStatus | 信息 | 下一步操作 |
| 表示支付会话创建成功。 | 商户客户端通过 paymentSessionData 调用 SDK。 |
| 表示由于未知原因支付会话创建失败。 | 请更换 paymentRequestId 重新调用接口以解决问题。如果问题未解决，请联系 Antom 技术支持。 |
| 表示支付会话创建失败。 | 请检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。 |
注意：如果您未收到响应报文，可能是网络超时所致。请更换 paymentRequestId 重新调用接口以解决问题。
步骤 2：嵌入 Antom Checkout Page
SDK 是用于处理支付流程的组件，为了收集信息以及根据 支付会话创建（收银台）接口中指定的支付方式在应用间切换，您需要通过创建支付会话来启动 SDK，具体操作请参阅嵌入模式集成文档。
步骤 3：获取支付结果
在买家完成支付或支付超时后，您可以接收来自 Antom 的异步通知或通过主动查询来获取支付结果，具体步骤请参阅异步通知处理和查询交易。
步骤 4：请款
Antom 提供自动请款和手动请款两种请款方式，您可根据业务需求自行选择。请款后，您可以通过异步通知或主动查询来获取请款结果。具体操作请参阅请款。
支付后操作
完成支付后，您可对交易进行以下支付后的操作：
退款
若您需要了解 Antom 的退款规则及如何对成功的交易发起退款，详情请参见退款。
争议
若买家选择使用卡支付方式，会涉及到争议相关的集成，详情请参见争议。
对账
交易完成后，使用 Antom 提供的财务报告进行对账。有关如何对账和 Antom 结算规则的更多信息，请参阅对账。
更多内容
卡支付特性
卡支付特性同样适用于 Apple Pay，以下列举了卡支付特性在 Apple Pay 的支持情况：
类型 | 是否支持 | 说明 |
条件支持 |
| |
| COF | 条件支持 | 仅 MIT（商户发起交易）场景支持。 |
| 3D Secure 2 | 支持 | Apple Pay 在完成 3D Secure 2 认证后，会将加密的交易凭证（Cryptogram）和电子商业指示器（ECI）传递至 Antom。Antom 将遵循第三方卡组织的标准流程处理这些认证信息，详情请参阅 Apple Developer: Payment token format reference。因此，Checkout Page 上不会再次出现由支付方式发起的 3DS 认证流程，用户体验无缝衔接。建议您在发起支付请求时，使用 is3DSAuthentication 和 enableAuthenticationUpgrade 参数的默认值。 |
| Antom 3DS Retry | 支持 | 无。 |
| MIT | 支持 | 无。 |
分期付款 | 不支持 | 无。 |
指定支付方式
您可以在 Antom Dashboard 的 支付 > 收银台设置 > 支付方式 中配置指定支付方式。您也可以通过在 支付会话创建（收银台）接口传入参数，指定在 Checkout Page 上展示的支付方式、支付方式列表的排序，以及极速支付方式的展示。
注意：如果您通过接口传入参数来指定支付方式，则优先取接口传值。
此功能为您带来以下优势：
- 根据您的业务地区过滤当地的支付方式
- 按照您的偏好对支付方式进行排序
- 可以将主流的支付方式如 Alipay、Apple Pay、Google Pay 以极速支付的形式展示
要指定 Apple Pay 为唯一支付方式，请在 支付会话创建（收银台）接口的 availablePaymentMethod 参数中，传入以下参数：
以下是指定 Apple Pay 为唯一支付方式的示例代码：
{
"availablePaymentMethod": {
"paymentMethodTypeList": [
{
"paymentMethodType": "APPLEPAY",
"expressCheckout": true,
"paymentMethodOrder": "0"
}
]
}
}