全托管模式

APO Checkout Page 是一款高效便捷的低代码集成支付页面产品,支持多种主流支付方式并覆盖全球多个地区,满足不同市场和场景的需求。通过简单的开发配置,您即可快速搭建一个界面专业、功能齐全的收银台页面,为买家提供流畅便捷的支付体验,同时显著提升支付接入效率,助力业务增长。

本方案通过接口实现集成,买家在完成商品加购后可直接跳转至 APO Checkout Page 进行支付,无需额外页面配置。

用户体验

下图展示一般场景下,从商户页面跳转至 APO Checkout Page 的用户体验流程:

Pc.png

下图展示在部分支付方式需跳转的场景下,从商户页面跳转至 APO Checkout Page,再跳转至第三方支付页面的用户体验流程

Pc-1.png

支付流程

使用 APO Checkout Page 全托管模式支付的流程包括以下步骤:

APO 全托管最新.png

  1. 买家在商户侧下单。
  2. 创建 支付会话创建 请求。

当买家在商户侧下单,您调用 支付会话创建 接口获取 APO Checkout Page 的 H5 链接。

  1. 处理 APO Checkout Page URL。

商户前端加载 APO Checkout Page URL (normalUrl),买家在 Checkout Page 上选择支付方式,然后完成支付。支付完成后会跳转至 Checkout Page 的结果页,然后再回到商家结果页。您可以支付会话创建 接口中的 paymentRedirectUrl 参数传入跳转地址。如果该支付方式背后支持了多个收单机构,APO 则会根据您指定的支付路由规则进行路由。

  1. 获取支付结果。

通过异步通知获取支付结果。 在 支付会话创建 接口中设置 paymentNotifyUrl 参数,以指定接收异步通知的地址。当支付请求成功或过期时,APO 会通过 支付通知 接口向您发送异步通知。

注意:

  • 当支付方式是卡、Apple Pay、Google Pay、PayPal 时,APO 还会额外通过 请款通知 接口发送请款结果给您。您需要依赖请款成功作为发货依据。
  • 若在多机构下开通了同一个支付方式,请在 APO Dashboard 完成路由配置。若不配置,则 APO 会采取随机路由规则。

集成准备

集成 APO 服务端 SDK 资源包,并完成接口库安装和请求示例初始化。具体操作参见服务端 SDK

集成步骤

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

  1. 创建支付会话
  2. 跳转至 APO Checkout Page
  3. 异步通知处理 

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

您在开通 APO 服务时可以指定支付方式。若需配置支付方式,请参见指定支付方式。当买家进行支付时,您需要收集关键信息,如支付请求 ID、订单信息、支付重定向链接和支付结果通知链接。您可以调用 支付会话创建 接口并传入订单信息,创建支付会话后跳转至 APO Checkout Page。

1. 调用支付会话创建接口

以下示例代码展示了如何调用 支付会话创建 接口:

copy
public static void createPaymentSession() {
    AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
    alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
    alipayPaymentSessionRequest.setProductScene(ProductSceneConstants.CHECKOUT_PAYMENT);

    // 设置金额
    Amount amount = Amount.builder().currency("SGD").value("6000").build();
    alipayPaymentSessionRequest.setPaymentAmount(amount);

    // 替换为您的 paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

    // 替换为您的 orderId
    String orderId = UUID.randomUUID().toString();

    // 设置买家信息
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // 设置商品信息
    Goods goods = Goods.builder().goodsBrand("Antom Brand").goodsCategory("outdoor goods/bag").goodsName("Classic Woman Bag").goodsQuantity("1")
    .goodsSkuName("Black").goodsImageUrl("https://mdn.alipayobjects.com/portal_pdqp4x/afts/file/A*H8M9RrxlArAAAAAAAAAAAAAAAQAAAQ")
    .goodsUnitAmount(amount).goodsUrl("https://yourGoodsUrl").referenceGoodsId("yourGoodsId").build();

    // 设置订单信息
    Order order = Order.builder().referenceOrderId(orderId)
    .orderDescription("antom ckp testing order").orderAmount(amount).buyer(buyer).goods(Stream.of(goods).collect(Collectors.toList())).build();
    alipayPaymentSessionRequest.setOrder(order);

    // 替换为您的通知地址
    // 或者在这里配置您的通知地址: <a href="https://dashboard.antom.com/global-payments/developers/iNotify">Notification URL</a>
    alipayPaymentSessionRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com/payment/receiveNotify");
    // 替换为您的跳转地址
    alipayPaymentSessionRequest.setPaymentRedirectUrl(
        "http://localhost:8080/index.html?paymentRequestId=" + paymentRequestId);

    AlipayPaymentSessionResponse alipayPaymentSessionResponse;
    try {
        System.out.println("paymentSession request: " + JSON.toJSONString(alipayPaymentSessionRequest));
        alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
        System.out.println("paymentSession response: " + JSON.toJSONString(alipayPaymentSessionResponse));
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // 处理错误情况
    }
}

2. 创建支付会话

如果您的支付方式中包含卡支付,支付会话参数中必须传入商户端的买家信息。详情请参见卡支付

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

类型

字段

是否必需

描述

基础字段

productCode

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

productScene

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

paymentRequestId

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

商户请求以订单币种收取的支付金额。需按下单币种的最小单位设置,如 CNY 为分,KRW 为元。

paymentRedirectUrl

商户端支付结果页。需根据服务端结果展示,非固定为成果页,必须为 HTTPS 地址。
paymentNotifyUrl

支付结果通知地址,可通过接口指定或在 APO Dashboard 上设置固定值。如果通过 APO Dashboard 设置,则该字段不可传。必须为 HTTPS 地址。
settlementStrategy

该参数只对 Antom 收单机构生效,用于该笔支付的结算策略。如果您签署了多个结算币种,需在接口中指定 settlementCurrency

locale

商户指定的 APO Checkout Page 展示语言。若传入语言不支持则默认展示英文。

订单字段

order.orderAmount

商户端订单金额。

order.referenceOrderId

商户端订单号。

order.orderDescription

商户端订单描述。

order.goods

详细商品信息。

注意

  • 当支付方式是 PayPal 时,此参数必传
  • 所有商品的金额总和需要等于 paymentAmount/orderAmount
  • 如果是虚拟商品,请指定参数 order.goods.deliveryMethodType 的值为 DIGITAL

order.shipping

配送信息。

注意当支付方式是 PayPal 且此交易是实物销售时,此参数必传

以上参数是创建支付会话的基本参数,完整参数和特定支付方式的额外要求请参考 支付会话创建

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

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"
  },
  "paymentFactor":{
    "isAuthorization":true
  },
  "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 表示支付会话创建成功。

获取 APO Checkout Page 链接(normalUrl) 并返回给商户前端。具体操作步骤请参见步骤 2

U表示由于未知原因支付会话创建失败。更换 paymentRequestId 重新调用接口以解决问题。如果问题未解决,请联系 APO 技术支持。
F表示支付会话创建失败。请检查并验证当前接口所需的请求字段(包括头部字段和正文字段)是否正确传递并有效。

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

步骤 2:跳转至 APO Checkout Page 客户端

商户服务端获取 normalUrl 后,将该 normalUrl 传递给前端,由商户前端跳转至 APO Checkout Page 页面。

获取 normalUrl 后,您需要在浏览器将页面重定向至 APO Checkout Page 页面,或在新标签页打开。

copy
if (serverResponse.normalUrl != null) {
    window.open(serverResponse.normalUrl, '_blank');
}

下图为跳转的 APO Checkout Page 渲染页面:

image

步骤 3:异步通知处理服务端

1. 设置接收通知的 webhook URL

您可以选择以下两种方法中的一种来设置接受通知的 webhook URL:

  • 若您的每个订单都有单独的通知 URL,建议您在每笔请求中设置 webhook URL。您可以通过 支付会话创建 接口请求的 paymentNotifyUrl 字段传入该笔订单的接收异步通知 URL。
  • 若您的所有订单都有一个统一的通知 URL,您则可以 APO Dashboard > 开发者 > 通知地址 中设置 webhook URL。

APM 支付

当支付成功或失败时,APO 会向您在 支付会话创建 接口的 paymentNotifyUrl 参数中指定的地址发送异步通知(支付通知)。收到 APO 的通知后,您需要按照返回收到确认信息返回响应。同时建议保存收单机构相关信息( acquirerInfo 参数),具体原因请查看单号说明 

APO 允许您在 支付会话创建 接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同,也可以在 APO Dashboard 中配置该地址。

以下代码展示了通知请求的示例: 

copy
{
    "acquirerInfo": {
        "acquirerMerchantId": "21********99147",
        "acquirerName": "ALIPAY",
        "acquirerResultCode": "SUCCESS",
        "acquirerResultMessage": "success",
        "acquirerTransactionId": "2025061819********0188540299977984",
        "referenceRequestId": "PAYMENT_20250618100222331_AUTO"
    },
    "customsDeclarationAmount": {
        "currency": "CNY",
        "value": "10"
    },
    "notifyType": "PAYMENT_RESULT",
    "paymentAmount": {
        "currency": "CNY",
        "value": "10"
    },
    "paymentCreateTime": "2025-06-17T19:02:31-07:00",
    "paymentId": "2025061819********0188540299977984",
    "paymentMethodType": "ALIPAY_CN",
    "paymentRequestId": "PAYMENT_20250618100222331_AUTO",
    "paymentResultInfo": {

    },
    "paymentTime": "2025-06-17T19:02:50-07:00",
    "pspCustomerInfo": {
        "pspCustomerId": "20*******9879519",
        "pspName": "ALIPAY_CN"
    },
    "pspPaymentId": "2025061*********11432765638",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

您可能会收到请求报文中 result.resultStatus 字段的不同值,请您根据下表指引进行处理:

result.resultStatus

信息

下一步操作

S

表示支付成功。

您可推进订单状态,并使用以下字段信息进行支付的后续操作。

  • paymentRequestId :用于咨询、取消和对账的支付请求 ID。
  • paymentId :表示由 APO 生成的支付订单 ID,用于退款和对账。
  • paymentAmount :表示支付金额。
  • paymentMethodType :表示买家使用的支付方式。

F

表示支付失败。请您引导买家重新下单。

常见问题

问:何时会发送通知?

答:不同场景异步通知的发送时间不同。

  • 如果支付成功,APO 通常会在 3 到 5 秒内发送异步通知。对于某些支付方式,如柜台支付(OTC),通知可能会稍有延迟。
  • 如果买家未提交支付,在支付会话超时时, APO 不会发送异步通知。

注意:支付会话默认有效期为 1 小时,不同机构的不同支付方式关闭订单所需时间会有所不同,通常 Antom 下的支付方式默认为 14 分钟,但例如 PayEasy、Kobini 是 7 天。

问:买家提交支付后多久能收到关单通知?

答:如果买家在支付会话有效期内选择某种支付方式提交支付,最长时延即为最终的支付方式超时时间加上支付会话有效期,例如支付会话有效期为一小时,买家在 59 分钟时选择银行转账支付且未最终支付,那您则会在 59 分钟 + 48 小时后(各支付方式超时不一致时间)收到关单的异步通知。

问:异步通知会被重新发送吗?

答:是的,对于以下情况,异步通知会在 24 小时内自动重新发送:

  • 由于网络原因未收到异步通知。
  • 您收到来自 APO 的异步通知后,没有按照处理通知的示例代码格式对通知做出响应。

通知至多重发 8 次或直至收到正确响应终止发送。发送间隔如下:0 分钟,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时,15 小时。

问:在通知中需要使用哪些关键参数?

答:通知中存在以下关键参数:

  • result:代表订单的支付结果。
  • paymentRequestId:商户生成的支付请求号,用于查询、撤销、对账。
  • paymentId:APO 生成的支付单号,用于退款、对账。
  • paymentAmount:如有金额核对的需求,可以消费这个字段。
  • paymentMethodType:表示买家使用的支付方式。
  • acquirerInfo:表示收单机构的相关信息。

问:有两个异步通知类型,应该用哪一个作为发货的依据?

答:当商户收到 notifyTypePAYMENT_RESULT 类型的通知时,需要优先判断 paymentMethodType 是否为 CARD/APPLEPAY/GOOGLEPAY/PAYPAL,若不为 CARD/APPLEPAY/GOOGLEPAY/PAYPAL,则可根据该通知结果选择是否发货。如果为 CARD/APPLEPAY/GOOGLEPAY/PAYPAL,需要等待 CAPTURE_RESULT 类型通知,再决策是否发货。

2. 异步通知验签

若您收到 APO 的异步通知,需要您在返回中按照示例代码格式返回响应,但无需做加签处理。

您需要对 APO 发送的支付通知进行验签。

copy
/**
 * receive notify
 *
 * @param request    request
 * @param notifyBody notify body
 * @return Result
 */
@PostMapping("/receiveNotify")
@ResponseBody
public Result receiveNotify(HttpServletRequest request, @RequestBody String notifyBody) {
    // 从 http 请求中获取所需参数  
    String requestUri = request.getRequestURI();
    String requestMethod = request.getMethod();
    // retrieve the required parameters from request header
    String requestTime = request.getHeader("request-time");
    String clientId = request.getHeader("client-id");
    String signature = request.getHeader("signature");
    try {
        // 通知验签
        boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId,
                                                          requestTime, signature, notifyBody, ANTOM_PUBLIC_KEY);
        if (!verifyResult) {
            throw new RuntimeException("Invalid notify signature");
        }
        // 反序列化通知主体
        JSONObject jsonObject = JSON.parseObject(notifyBody);
        String notifyType = (String)jsonObject.get("notifyType");
        if("PAYMENT_RESULT".equals(notifyType)){
            AlipayPayResultNotify paymentNotify = jsonObject.toJavaObject(AlipayPayResultNotify.class);
            if (paymentNotify != null && "SUCCESS".equals(paymentNotify.getResult().getResultCode())) {
                // 处理您自己的业务逻辑
                // 例如:支付信息与买家之间的关系保存在数据库中。  
                System.out.println("receive payment notify: " + JSON.toJSONString(paymentNotify));
                return Result.builder().resultCode("SUCCESS").resultMessage("success.").resultStatus(ResultStatusType.S).build();
            }
        }else if("CAPTURE_RESULT".equals(notifyType)){
            AlipayCaptureResultNotify captureNotify = jsonObject.toJavaObject(AlipayCaptureResultNotify.class);
            if (captureNotify != null && "SUCCESS".equals(captureNotify.getResult().getResultCode())) {
                // 处理您自己的业务逻辑
                System.out.println("receive capture notify: " + JSON.toJSONString(captureNotify));
                return Result.builder().resultCode("SUCCESS").resultMessage("success.").resultStatus(ResultStatusType.S).build();
            }
        }
    } catch (Exception e) {
        // 处理错误情况
        return Result.builder().resultCode("FAIL").resultMessage("fail.").resultStatus(ResultStatusType.F).build();
    }
    return Result.builder().resultCode("SYSTEM_ERROR").resultMessage("system error.").resultStatus(ResultStatusType.F).build();
}

您无需对响应通知结果做加签处理,但是对于每个通知请求均需按以下固定格式响应,与订单支付成功与否无关。

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    }
}

支付后操作

查询交易

除了可以通过异步通知的功能获取买家的支付结果,同时也支持您通过主动查询服务来获取对应的结果。您可以调用 支付结果查询 接口,可使用支付会话中的 paymentRequestId 查询支付状态。

以下代码展示了如何调用 支付结果查询 接口:

copy
public static void inquiryPayment() {
    AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();
    // 替换您的 paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");
    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // 处理错误情况
    }
}

建议保存收单机构相关信息( acquirerInfo 参数),具体原因请查看单号说明。以下代码展示了一个响应报文的示例:

copy
{
    "acquirerInfo": {
        "acquirerMerchantId": "76476400001****",
        "acquirerName": "2C2P",
        "acquirerTransactionId": "823c1fe4-1168-4abc-9687-c42f3269****",
        "referenceRequestId": "202504301903130001032028917****"
    },
    "acquirerReferenceNo": "202504301903130001032028917****",
    "paymentAmount": {
        "currency": "USD",
        "value": "110"
    },
    "paymentCreateTime": "2025-04-30T00:16:12-07:00",
    "paymentId": "2025043019401089010011132026330****",
    "paymentMethodType": "MIXEDCARD",
    "paymentRequestId": "PAYMENT_20250430151543077_****",
    "paymentResultCode": "SUCCESS",
    "paymentResultInfo": {
        "cardholderName": "*******"
    },
    "paymentResultMessage": "success.",
    "paymentStatus": "SUCCESS",
    "paymentTime": "2025-04-30T00:16:14-07:00",
    "transactions": [
        {
            "acquirerInfo": {
                "acquirerMerchantId": "76476400001****",
                "acquirerName": "2C2P",
                "referenceRequestId": "202504301903130101032028917****"
            },
            "transactionAmount": {
                "currency": "USD",
                "value": "110"
            },
            "transactionId": "2025043019401089010011132026318****",
            "transactionRequestId": "PAYMENT_20250430151543077_****",
            "transactionResult": {
                "resultCode": "SUCCESS",
                "resultMessage": "success",
                "resultStatus": "S"
            },
            "transactionStatus": "SUCCESS",
            "transactionTime": "2025-04-30T00:16:15-07:00",
            "transactionType": "CAPTURE"
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

响应报文中 paymentMethodType 和 transactions.transactionType 字段的值将表示不同的状态。以下列出具体场景下返回值的说明:

当 paymentMethodType 不为 CARDAPPLEPAY 或 GOOGLEPAY 时,您需根据响应报文里 paymentStatus(支付状态)进行处理。返回的值包括:

  • SUCCESS表示支付成功。
  • FAIL:表示支付失败。

注意:在查询交易时,如果买家没有提交订单,就会一直报错 ORDER_NOT_EXIST,提交订单以后才不会报错。

退款

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

争议

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

对账

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

支付方式特性

卡支付

如果您的支付方式中包含卡支付,支付会话参数中必须传入商户端的买家信息。在 order.buyer 字段中,至少需要提供 referenceBuyerIdbuyerPhoneNo 或 buyerEmail 三者中的一项。如果未传入买家信息,买家在选择卡支付方式并提交支付时,页面将出现错误,导致支付流程无法完成。

copy
{
    "order": {
        ...
        "buyer": {
            "referenceBuyerId": "88888888",
            "buyerEmail": "gaga@test.com",
            "buyerPhoneNo": "18888888888"
        }
    },
...
}

启用 3D Secure2

若您想了解有关 3D Secure2 的详细信息,请参阅 3D Secure2 验证

  • 您可以根据自身的风险评估,通过 支付会话创建 接口指定参数 availablePaymentMethod.paymentMethodMetaData.is3DSAuthentication 的值为 TRUE,此时 APO 会设置该笔交易为 3D 验证 传递给下游收单机构。
  • 若您不设置该参数或设置参数 availablePaymentMethod.paymentMethodMetaData.is3DSAuthentication 的值为 FALSE,APO 会设置该笔交易为非 3D 验证传递给下游收单机构,但是最后会以收单机构的处理为准。
copy
{
  ...
    "availablePaymentMethod": {
        "paymentMethodMetaData": {
            "is3DSAuthentication": true
        }
    },  
  ...
}

当交易通过 3DS 认证后,会在异步通知中增加对应的 3DS 信息,见 paymentResultInfo.threeDSResult 字段。

copy
{
    "acquirerInfo": {
        "acquirerMerchantId": "219117000551****",
        "acquirerName": "ALIPAY",
        "acquirerResultCode": "SUCCESS",
        "acquirerResultMessage": "success",
        "acquirerTransactionId": "2025043019401080010019178029053****",
        "referenceRequestId": "PAYMENT_20250430155835598_****"
    },
    "notifyType": "PAYMENT_RESULT",
    "paymentAmount": {
        "currency": "GBP",
        "value": "100"
    },
    "paymentCreateTime": "2025-04-30T00:59:08-07:00",
    "paymentId": "20250430194010800100191780290533000",
    "paymentMethodType": "CARD",
    "paymentRequestId": "PAYMENT_20250430155835598_AUTO",
    "paymentResultInfo": {
        "avsResultRaw": "U",
        "cardBin": "53**32",
        "cardBrand": "MASTERCARD",
        "cardCategory": "CONSUMER",
        "cardNo": "************1310",
        "cardholderName": "*******",
        "cvvResultRaw": "U",
        "expiryMonth": "**",
        "expiryYear": "**",
        "funding": "CREDIT",
        "issuingCountry": "CN",
        "lastFour": "1310",
        "paymentMethodRegion": "GLOBAL",
        "threeDSResult": {
            "cavv": "kAPDv**********+btfgoJhBG+N",
            "eci": "02",
            "threeDSOffered": true,
            "threeDSVersion": "2.2.0"
        }
    },
    "paymentTime": "2025-04-30T00:59:28-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

APM 支付

Antom Przelewy24

当买家选择 Antom Przelewy24 支付时,可通过以下方式优化邮箱输入体验:

您可以在 支付会话创建 接口中传入availablePaymentMethod.paymentMethodMetaData.payerEmail 参数,  APO Checkout Page 将自动在支付选项中预填充该邮箱,无需您手动输入。

示例代码:

copy
{
  ...
    "availablePaymentMethod": {
        "paymentMethodMetaData": {
            "payerEmail": "123221321@test.com",
        }
    },  
  ...
}

买家在选择 Antom Przelewy24 支付时,会预填充邮箱地址:

p1.png

Mercado pago

当买家选择 Mercado pago 支付时,将涉及的字段如下:

收单机构

支付方式

收集支付要素

支付要素参数名

最佳实践

Antom

Mercado Pago(巴西)

巴西个人税号

paymentMethodMetaData.cpf

引导买家在商户页面输入巴西个人税号,并手动打开 Mercado Pago 应用完成支付。

Antom

Mercado Pago

巴西、墨西哥、智利和秘鲁)

买家的电子邮件 

paymentMethodMetaData.payerEmail 

引导买家在商户页面输入电子邮件,并手动打开 Mercado Pago 应用来完成支付。 

您可以通过以下方式优化邮箱或巴西个人税号输入体验:

  • 您可以在支付会话接口中传入availablePaymentMethod.paymentMethodMetaData.payerEmail 参数,  APO Checkout Page 将自动在支付选项中预填充该邮箱,无需您手动输入。
  • 您也可以在支付会话接口中传入availablePaymentMethod.paymentMethodMetaData.cpf 参数,  APO Checkout Page 将自动在支付选项中预填充巴西税号,无需您手动输入。

示例代码:

copy
{
  ...
    "availablePaymentMethod": {
        "paymentMethodMetaData": {
            "payerEmail": "123221321@test.com",
        }
    },  
  ...
}

买家在选择 Mercado Pago 支付时,会预填充邮箱地址:

全托管模式

更多内容

指定支付方式

您可以通过后台配置或修改 支付会话创建 接口的参数来指定 APO Checkout Page 支付方式的显示,支付方式列表排序,以及极速支付方式的展示。

注意:如需通过后台配置支付方式,请联系APO技术支持

优势

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

如何启用

您可以通过接口参数传入或 APO Dashboard收银台页面 > 支付方式 中配置指定支付方式。如果您通过接口传入,则优先取接口传值。

接口参数传入

指定并过滤支付方式展示

copy
{ ...
  "availablePaymentMethod": {
    "paymentMethodTypeList": [
      {
        "paymentMethodType": "ALIPAY_CN",
        "expressCheckout": true,
        "paymentMethodOrder": "0"
      },
      {
        "paymentMethodType": "TNG",
        "expressCheckout": false,
        "paymentMethodOrder": "1"
      }
    ]
  }
}

支付方式排序

copy
{ ...
  "availablePaymentMethod": {
    "paymentMethodTypeList": [
      {
        "paymentMethodType": "ALIPAY_CN",
        "expressCheckout": true,
        "paymentMethodOrder": "0"
      },
      {
        "paymentMethodType": "TNG",
        "expressCheckout": false,
        "paymentMethodOrder": "1"
      }
    ]
  }
}

极速支付方式展示

copy
{ ...
  "availablePaymentMethod": {
    "paymentMethodTypeList": [
      {
        "paymentMethodType": "ALIPAY_CN",
        "expressCheckout": true,
        "paymentMethodOrder": "0"
      },
      {
        "paymentMethodType": "TRUEMONEY",
        "expressCheckout": false,
        "paymentMethodOrder": "1"
      }
    ]
  }
}

APO Tokenization

如果买家选择卡支付,Checkout Page 可以允许买家通过 APO Tokenization 的能力在首次支付时保存卡信息,在后续的支付中则无需重新输入信息,Checkout Page 即可展示买家的脱敏卡号进行支付。

您可以通过保存和传递买家卡的令牌信息完成存卡支付,买家体验如下:

image

优势

  • 让买家存储他们的付款方式,以便下次获得更快的结账体验。
  • 存储支付方式信息后,显示详细的支付方式信息可以增加买家支付时的信任度。
  • 数据显示,使用 cardToken 支付可以获得更高的支付成功率。
  • cardToken 无支付机构使用限制,开通的机构都能使用。

如何启用

您可以通过以下步骤完成已存卡交易

  1. 显示绑卡按钮。通过 支付会话创建 接口指定 availablePaymentMethod.paymentMethodMetaData.tokenizeMode 字段的值为  ASKFORCONSENT可以在 APO Checkout Page 的卡支付选项中展示存卡按钮。
copy
{
...
    "availablePaymentMethod": {
        "paymentMethodMetaData": {
            "tokenizeMode": "ASKFORCONSENT"
        }
    }
}
  1. 首次支付后绑卡。当买家在您的页面保存银行卡信息时,请务必将其与买家信息关联,并在您的服务端保存相应的银行卡信息。( 从 支付通知 接口中的 paymentResultInfo 字段中获取 cardToken 的值)。
copy
{
    "acquirerInfo": {
        "acquirerMerchantId": "219117000551****",
        "acquirerName": "ALIPAY",
        "acquirerResultCode": "SUCCESS",
        "acquirerResultMessage": "success",
        "acquirerTransactionId": "2025043019401080010019178029053****",
        "referenceRequestId": "PAYMENT_20250430155835598_****"
    },
    "notifyType": "PAYMENT_RESULT",
    "paymentAmount": {
        "currency": "GBP",
        "value": "100"
    },
    "paymentCreateTime": "2025-04-30T00:59:08-07:00",
    "paymentId": "2025043019401080010019178029053****",
    "paymentMethodType": "CARD",
    "paymentRequestId": "PAYMENT_20250430155835598_****",
    "paymentResultInfo": {
        "avsResultRaw": "U",
        "cardBin": "53**32",
        "cardBrand": "MASTERCARD",
        "cardCategory": "CONSUMER",
        "cardNo": "************1310",
        "cardToken": "ALIPAY5ITT+wDZhYuE1f********************vJ5BksK4yWCloE4MwfmN48sP1+rSPQ==",
        "cardholderName": "*******",
        "cvvResultRaw": "U",
        "expiryMonth": "**",
        "expiryYear": "**",
        "funding": "CREDIT",
        "issuingCountry": "CN",
        "lastFour": "1310",
        "networkTransactionId": "MCGQ120DH****",
        "paymentMethodRegion": "GLOBAL",
        "threeDSResult": {
            "cavv": "kAPDv**********+btfgoJhBG+N",
            "eci": "02",
            "threeDSOffered": true,
            "threeDSVersion": "2.2.0"
        }
    },
    "paymentTime": "2025-04-30T00:59:28-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}
  1. 后续使用 cardToken 支付。当买家存在已保存的银行卡时,您需要通过 支付会话创建 接口传递卡的令牌信息,从而在 APO 收银台展示买家已存卡,买家可以使用已存卡完成支付。

以下示例展示了买家使用已存银行卡支付时,支付会话创建 接口使用银行卡令牌发起的请求示例:

copy
{
  ...
    "savedPaymentMethods": [
        {
            "paymentMethodType": "CARD",
            "paymentMethodId": "ALIPAYEfG2DFbGx2Eh739qU+VMnCPEe7MfRKfMfC5k7k/IFASWpAh/vCxHV3dPYpbkGz1iyWCloE4MwfmN48sP8+rS****"
        }
    ]
}