Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

集成 Google Pay 支付

通过 Google Pay 服务，买家可以使用存储在其 Google Pay 账户中的信用卡或借记卡进行支付。借助 Antom Checkout Page，您无需额外集成 Google Pay 的 SDK，Checkout Page 将会为您加载 Google Pay 服务，并可将 Google Pay 配置为极速支付方式。

用户体验

web-embed.png

集成准备

在您开始集成前，请阅读集成指南及接口概述文档，了解服务端接口的集成步骤及调用接口的注意事项，并确保已完成以下预配置：

  • 已获得 client ID。
  • 已完成密钥配置。
  • 已完成异步通知接收地址的配置。
  • 集成服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
  • 参阅 Web/WAP 端集成 SDK 资源包文档来集成客户端 SDK 资源包，并注意使用最新或不低于 1.41.0 版本的 SDK。

集成步骤

请按照以下步骤开始集成：

  1. 创建支付会话
  2. 嵌入至 Antom Checkout Page
  3. 获取支付结果
  4. 发起请款

步骤 1：创建支付会话 服务端

您可以调用 支付会话创建（收银台）接口并传入订单信息，创建支付会话后跳转至 Antom Checkout Page。

以下是请求参数重点字段：

类型

字段

是否必需

描述

基础字段

productCode

是

此场景下该字段的值固定为 CASHIER_PAYMENT。

productScene

是

此场景下该字段的值固定为 CHECKOUT_PAYMENT。

paymentRequestId

是

商户为识别支付请求而分配的专属 ID。

paymentAmount

是

商户请求以订单币种收取的支付金额。

paymentRedirectUrl

是

支付完成后买家被重定向到的商户页面链接。

paymentNotifyUrl

否

支付结果通知地址，可通过接口指定或在 Antom Dashboard 上设置固定值。

settlementStrategy

否

支付请求的结算策略。如果您签署了多个结算币种，需在接口中指 settlementCurrency。

locale

否

商户指定的 Antom Checkout Page 展示语言。如果该字段为空或设置为自动，则将使用浏览器的默认语言设置，通常为英文。

paymentFactor.isAuthorization

否

表示支付场景是否为授权场景。有效值为：

  • false：默认值。表示支付场景为常规支付，无需授权。
  • true：表示支付场景为授权场景。

注意：在 Checkout Page（CKP）集成中，无需设置此参数。

订单字段

order.orderAmount

是

商户端订单金额。

order.referenceOrderId

是

商户端订单号。

order.orderDescription

是

商户端订单描述。

order.buyer

是

商户端买家信息。至少需要提供以下三者其中一个信息： 

  • order.buyer.referenceBuyerId
  • order.buyer.buyerPhoneNo
  • order.buyer.buyerEmail 

注意：如果未传入买家信息，买家在选择 Google Pay 为支付方式并提交支付时，页面将出现错误，导致支付流程无法完成。

设置 Google Pay 的相关参数

availablePaymentMethod.paymentMethodMetaData.googlePayConfiguration

否

在 Checkout Page 场景下，该参数建议使用缺省值。

注意：您也可以通过设置该参数指定 Google Pay 为收银台中唯一支付方式，详情参见指定支付方式。

指定 Google Pay 为极速支付方式

availablePaymentMethod.paymentMethodTypeList.expressCheckout

否

您可以通过设置该参数的值为 true 或者在 Antom Dashboard 配置 Google Pay 为极速支付方式。

以上参数是创建支付会话的基本参数，完整参数和特定支付方式的额外要求请参考 支付会话创建（收银台）。

以下代码展示了如何调用 支付会话创建（收银台）接口：

copy
  /**
     * show how to card payment Session(need to finish payment by Antom SDK)
     */
    public static void executePaymentSessionCreateWithGooglePay() {

        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("GOOGLEPAY");
        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();
            // 处理错误情况
        }
    }

以下代码展示了一个请求报文的示例：

copy
{
  "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": "GOOGLEPAY",
        "expressCheckout": false,
        "paymentMethodOrder": 1
      }
    ]
  },
  "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 的跳转链接。（在嵌入式场景下，可以忽略此字段。）
copy
{
    "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

信息

下一步操作

S

表示支付会话创建成功。

商户客户端通过 paymentSessionData 调用 SDK。

U

表示由于未知原因支付会话创建失败。

请更换 paymentRequestId 重新调用接口以解决问题。如果问题未解决，请联系 Antom 技术支持。

F

表示支付会话创建失败。

请检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。

注意：如果您未收到响应报文，可能是网络超时所致。请更换 paymentRequestId 重新调用接口以解决问题。

步骤 2：嵌入 Antom Checkout Page 客户端

SDK 是用于处理支付流程的组件，为了收集信息以及根据 支付会话创建（收银台）接口中指定的支付方式在应用间切换，您需要通过创建支付会话来启动 SDK，具体操作请参阅嵌入模式集成文档。

步骤 3：获取支付结果 服务端

在买家完成支付或支付超时后，您可以接收来自 Antom 的异步通知或通过主动查询来获取支付结果，具体步骤请参阅异步通知处理和查询交易。

步骤 4：请款 服务端

Antom 提供自动请款和手动请款两种请款方式，您可根据业务需求自行选择。请款后，您可以通过异步通知或主动查询来获取请款结果。具体操作请参阅请款。

支付后操作

完成支付后，您可对交易进行以下支付后的操作：

退款 服务端

若您需要了解 Antom 的退款规则及如何对成功的交易发起退款，详情请参见退款。

争议 服务端

若买家选择使用卡支付方式，会涉及到争议相关的集成，详情请参见争议。

对账 服务端

交易完成后，使用 Antom 提供的财务报告进行对账。有关如何对账和 Antom 结算规则的更多信息，请参阅对账。

更多内容

卡支付特性

卡支付特性同样适用于 Google Pay，以下列举了卡支付特性在 Google Pay 的支持情况：

类型

是否支持

说明

Antom Tokenization

条件支持

  • CIT（持卡人发起交易）场景不支持，建议您通过 Google 账户存卡。
  • MIT（商户发起交易）场景支持。

COF

支持

无。

3D Secure 2

支持

  • 您将 paymentMethodMetaData.googlePayConfiguration.allowedAuthMethods 参数设为 CRYPTOGRAM_3DS 或使用了默认值，并且 Google Pay 侧已经完成 3DS 验证，Antom 按第三方机构 3DS 处理流程，Checkout Page 不会出现支付方式侧 3DS 的体验，详情请参阅 Google Pay - 为全球符合条件的 Visa 设备令牌交易启用责任转移。
  • 您将 paymentMethodMetaData.googlePayConfiguration.allowedAuthMethods 参数设为 CRYPTOGRAM_3DS 和 PAN_ONLY
    或使用默认值，如 Google Pay 侧未完成 3DS 验证，Checkout Page会根据您传入的 is3DSAuthentication 和 enableAuthenticationUpgrade 决策是否需要 3DS 验证。
Antom 3DS Retry

支持

无。

MIT

支持

无。

指定支付方式

您可以在 Antom Dashboard 的 支付 > 收银台设置 > 支付方式 中配置指定支付方式。您也可以通过在 支付会话创建（收银台）接口传入参数，指定在 Checkout Page 上展示的支付方式、支付方式列表的排序，以及极速支付方式的展示。

注意：如果您通过接口传入参数来指定支付方式，则优先取接口传值。

此功能为您带来以下优势：

  • 根据您的业务地区过滤当地的支付方式
  • 按照您的偏好对支付方式进行排序
  • 可以将主流的支付方式如 Alipay、Apple Pay、Google Pay 以极速支付的形式展示

要指定 Google Pay 为唯一支付方式，请在 支付会话创建（收银台）接口的 availablePaymentMethod 参数中，传入以下参数：

以下是指定 Google Pay 为唯一支付方式的示例代码：

copy
{
  "availablePaymentMethod": {
    "paymentMethodTypeList": [
      {
        "paymentMethodType": "GOOGLEPAY",
        "expressCheckout": true,
        "paymentMethodOrder": "0"
      }
    ]
  }
}