Antom, leading provider of tailored payment solutions

托管模式

单笔支付服务为网站和应用程序提供全方位的支付解决方案,支持桌面端、移动端等多场景无缝对接。通过一次集成即可快速接入多种在线支付方式,包括电子钱包、网银转账和卡支付等,有效降低技术门槛。买家可以根据个人偏好选择最便捷安全的支付方式,享受更优质的支付体验。

本文为您介绍如何通过托管模式集成银行卡支付方式。通过托管模式集成银行卡支付,您可以将支付信息采集环节交由 Antom 处理。由于敏感的持卡人数据不经过您的服务器,此模式可帮助您免除 PCI-DSS 的合规负担,无需您自行构建符合 PCI-DSS 标准的支付环境,您也无需获取 PCI 合规资质。

用户体验

以下图片展示了买家进行首次支付或绑卡支付的用户体验:

首次支付

在首次支付时,可以引导买家勾选存储卡信息,在后续的支付中可用于绑卡支付、订阅支付、自动充值等场景,为买家提供更快捷的支付体验,同时大幅提升买家的支付意愿。

首次web.png

绑卡支付

买家直接选择已存卡进行支付,无需重新填写支付信息。

绑卡web.png

订单生命周期

卡支付订单主要包含以下阶段:

  1. 授权:买家使用银行卡完成支付后,其资金将处于冻结状态。买家下单至完成授权期间,您都可以在窗口期内对订单发起撤销。
  2. 请款:通过请款将买家的冻结资金转移到您的账户。Antom 默认自动为您请款,具体信息请参阅请款。请款完成后,若有需要,您可以在窗口期内发起退款。
  3. 拒付:若买家向发卡行发起拒付或调单查询,您需要根据情况处理争议流程,具体信息请参阅争议。

生命周期.png

支付流程

对于使用托管模式的卡支付,支付流程包括以下步骤:

托管式flow-cn.png

  1. 买家选择卡支付。
  2. 提交支付请求。
    买家提交支付后,您需调用 pay(单笔支付)接口来提交支付请求。
  3. Antom 采集卡信息。
    商户服务端获取 Antom 中间页链接用于采集卡信息,随后买家跳转至 Antom 中间页并输入卡信息,此时买家可以选择是否保存卡信息。
  4. (可选)买家跳转至 3DS 认证页面。
    买家跳转至 3DS 认证页面完成身份核验,随后返回商户结果页。
  5. 获取授权支付结果。
    商户服务端接收 Antom 返回的授权支付结果通知,并根据结果进行相应的业务处理。
  6. 获取请款结果。
    您可以通过以下两种方法之一获取请款结果:

集成准备

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

  • 已获得 client ID。
  • 已完成密钥配置。
  • 已完成异步通知接收地址的配置。
  • 集成服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。

集成步骤

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

  1. 授权支付
  2. 跳转至 Antom 中间页采集卡信息
  3. 获取授权支付结果
  4. 获取请款结果

步骤 1:授权支付 服务端

买家提交支付后,您需要采集买家的订单信息、设备信息和支付金额等关键信息,并调用 pay(单笔支付)接口提交支付请求。

以下是发起支付请求的重点参数:

类型

参数名称

是否必需

描述

基础参数

productCode

是

在此场景下,该参数的值固定为 CASHIER_PAYMENT。

paymentRequestId

是

商家为识别支付请求而分配的专属 ID,每次发起支付都要有一个新的 ID。

paymentAmount

是

支付金额,应根据订单货币的最小单位设置,例如,CNY 为分,KRW 为元。

paymentMethod.paymentMethodType

是

支付方式枚举值,卡支付场景下固定为 CARD。

paymentRedirectUrl

是

商户端支付结果页,需根据服务端结果展示,非固定成功页面。

paymentNotifyUrl

否

支付结果通知地址,可通过接口传递,也可通过 Antom Dashboard 设置为固定值。若两者都设置,则接口传递的值优先。

settlementStrategy

是

支付请求的结算策略。若业务签约了多个结算币种,则需在其中指定 settlementCurrency 参数。

paymentFactor.isAuthorization

是

支付模式。卡支付场景固定传 true,指定为授权请款模式。

订单参数

order.buyer

是

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

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

order.referenceOrderId

是

商户端订单号。

order.orderDescription

是

商户端订单描述。

设备参数

env.terminalType

是

商户服务适用的终端类型。有效值为:

  • WEB:客户端终端类型为网站,通过 PC 浏览器打开。
  • WAP:客户端终端类型为 H5 页面,通过移动浏览器打开。
  • APP:客户端终端类型为移动应用。

env.osType

否

买家发起交易的操作系统类型。有效值为:

  • IOS:表示操作系统为 iOS。
  • ANDROID:表示操作系统为 Android。

注意:当 env.terminalType 为 WAP 或 APP 时,请指定此参数。

env.clientIp

是

买家的 IP 地址,卡支付场景下需要提供此信息。

卡支付信息参数(具体请参考卡支付特性)

paymentMethod.paymentMethodMetaData.is3DSAuthentication

否

您需要根据当前交易的风险和拒付情况,决定交易是否进行 3DS 认证。有效值为:

  • true:指交易发起 3DS 认证。
  • false:指交易不进行 3DS 认证。如果此参数为空或未传递,默认为此值。

以上参数是发起支付请求的基本参数,完整参数和特定支付方式的额外要求请参考 pay(单笔支付)接口。

以下示例代码展示了如何调用 pay(单笔支付)接口:

public static void payByCard() {
    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("CARD").build();
    alipayPayRequest.setPaymentMethod(paymentMethod);

    // 卡信息
    Map<String, Object> paymentMethodMetaData = new HashMap<String, Object>();
    paymentMethodMetaData.put("tokenizeMode", "ASKFORCONSENT");
    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);

    // 设置授权请款模式
    PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
    alipayPayRequest.setPaymentFactor(paymentFactor);

    // 替换为您的通知地址
    alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

    // 替换为您的跳转 url
    alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    // 支付
    AlipayPayResponse alipayPayResponse = null;
    try {
        alipayPayResponse = CLIENT.execute(alipayPayRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // 处理错误信息
    }
}

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

{
    "settlementStrategy": {
        "settlementCurrency": "SGD"
    },
    "productCode": "CASHIER_PAYMENT",
    "paymentNotifyUrl": "https://www.yourNotifyUrl.com",
    "paymentRequestId": "PAY_20***********0638",
    "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
    "paymentFactor": {
        "isAuthorization": true,
        "captureMode": "AUTOMATIC"
    },
    "paymentMethod": {
        "paymentMethodMetaData": {
            "is3DSAuthentication":true
        },
        "paymentMethodType": "CARD"
    },
    "paymentAmount": {
        "currency": "SGD",
        "value": "7000"
    },
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "30000"
        },
        "orderDescription": "《Bad Romance》-Lady Gaga",
        "referenceOrderId": "ORDER_20***********0638",
        "buyer": {
            "buyerEmail": "gaga@gaga.com"
        }
    },
    "env": {
        "clientIp": "1.1.1.1",
        "osType": "IOS",
        "terminalType": "WAP"
    }
}

以下代码展示了发起支付后可能返回的响应报文示例,其中包含以下重点参数:

  • result.resultStatus:授权支付的状态。
  • normalUrl:需要跳转的 Antom 中间页链接,用于输入卡信息。
{
    "normalUrl": "https://ac.alipay.com/page/antom-web-checkout-v2/checkout-page/pages/payment/index.html?shadow=true&sessionData=lVLs6TlvaMcZjF0L4fLhBZbpfjbvq9bTl4T6NLBEg2mXqPfPsL%2FqBGcO2dv7O2iDUmb6aFO9f5MihRxiKENQFA%3D%3D%26%26SG%26%26188%26%26eyJleHRlbmRJbmZvIjoie1wiZGlzcGxheUFudG9tTG9nb1wiOlwidHJ1ZVwifSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBTEwiLCJwcm9kdWN0U2NlbmUiOiJDSEVDS09VVF9QQVlNRU5UIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJza2lwUmVuZGVyUGF5bWVudE1ldGhvZCI6ZmFsc2V9&shadow=true",
    "paymentActionForm": "{\"method\":\"GET\",\"paymentActionFormType\":\"RedirectActionForm\",\"redirectUrl\":\"https://ac.alipay.com/page/antom-web-checkout-v2/checkout-page/pages/payment/index.html?shadow=true&sessionData=lVLs6TlvaMcZjF0L4fLhBZbpfjbvq9bTl4T6NLBEg2mXqPfPsL%2FqBGcO2dv7O2iDUmb6aFO9f5MihRxiKENQFA%3D%3D%26%26SG%26%26188%26%26eyJleHRlbmRJbmZvIjoie1wiZGlzcGxheUFudG9tTG9nb1wiOlwidHJ1ZVwifSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBTEwiLCJwcm9kdWN0U2NlbmUiOiJDSEVDS09VVF9QQVlNRU5UIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJza2lwUmVuZGVyUGF5bWVudE1ldGhvZCI6ZmFsc2V9&shadow=true\"}",
    "paymentAmount": {
        "currency": "SGD",
        "value": "7000"
    },
    "paymentCreateTime": "2024-12-25T00:48:53-08:00",
    "paymentId": "202412251940109000001882***********",
    "paymentRequestId": "PAYMENT_20***********2284_AUTO",
    "paymentResultInfo": {},
    "redirectActionForm": {
        "method": "GET",
        "redirectUrl": "https://ac.alipay.com/page/antom-web-checkout-v2/checkout-page/pages/payment/index.html?shadow=true&sessionData=lVLs6TlvaMcZjF0L4fLhBZbpfjbvq9bTl4T6NLBEg2mXqPfPsL%2FqBGcO2dv7O2iDUmb6aFO9f5MihRxiKENQFA%3D%3D%26%26SG%26%26188%26%26eyJleHRlbmRJbmZvIjoie1wiZGlzcGxheUFudG9tTG9nb1wiOlwidHJ1ZVwifSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBTEwiLCJwcm9kdWN0U2NlbmUiOiJDSEVDS09VVF9QQVlNRU5UIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJza2lwUmVuZGVyUGF5bWVudE1ldGhvZCI6ZmFsc2V9&shadow=true"
    },
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process",
        "resultStatus": "U"
    }
}

下表展示了响应报文中 result.resultStatus 字段可能返回的值,请您根据指引进行处理:

result.resultStatus

信息

后续操作

F

授权支付失败。

请关闭当前交易或更换 paymentRequestId 重新下单。

U

交易处理中。

  • 若返回了 normalUrl,则将商户服务端跳转至该 Antom 中间页以采集买家的卡信息。同时,您需要储存 paymentId 用于后续的请款或退款操作。
  • 若没有收到 normalUrl,则表示交易异常,您可关闭当前交易或更换 paymentRequestId 重新下单。

注意:如果您未收到响应报文,可能是网络超时所致。您可关闭当前交易或更换 paymentRequestId 重新下单。

常见问题

问:paymentId 的作用是什么?应该如何消费?

答:如果您需要存储相应的订单号以备后续退款和对账,可以指定 paymentId。

问:terminalType 应该如何设置?

答:terminalType 的有效值为:

  • WEB:如果买家在 PC 端发起交易,需要将 terminalType 指定为 WEB。
  • WAP:如果买家在移动浏览器上发起交易,需要将 terminalType 指定为 WAP。添加 osType 参数,并根据买家的操作系统类型设置相应的参数 ANDROID 或 IOS。
  • APP:如果买家在移动应用内发起交易,需要将 terminalType 指定为 APP。

问:哪些交易需要设置为 3DS 交易?

答:若您购买了 Antom Shield,Antom 将基于实时风控模型、交易特征及历史数据,智能决策每笔交易是否需要进行 3DS 认证;若您自身具备完善的风控能力,您可根据订单风险、拒付率以及区域合规要求自行决策是否需触发 3DS 认证。flow.png

问:如果我不设置 is3DSAuthentication 参数,Antom 会为我决策是否发起 3DS 交易吗?

答:不会。如果您未设置 is3DSAuthentication 参数,则默认发起非 3DS 交易,此时存在盗卡、拒付等风险。只有您采购 Antom Shield 服务后,Antom 风控模型才会为您决策是否使用 3DS 验证,此时您无需设置 is3DSAuthentication 参数。

步骤 2:跳转至卡信息采集页面 客户端

商户服务端通过 pay(单笔支付)响应获取到卡信息采集链接(normalUrl)后,需要将该链接传递给客户端,由商户客户端跳转至 Antom 中间页以采集买家的卡信息。若交易需进行 3DS 认证,Antom 中间页将自动跳转至 3DS 认证页面,无需您进行额外处理。

获取 normalUrl 后,您需要在浏览器将页面重定向至卡信息采集页面,或在新标签页打开。

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

Antom 服务端会基于您传入的 paymentMethod 和 terminalType 返回不同的 normalUrl,例如 H5 页面https://checkout.antom.com/checkout-page/pages/payment/index.html?sessionData=T*****,这个页面在处理过程中可能会发生重定向。

以下图片展示了 Web 和 App 端重定向至卡信息采集页面(normalUrl)的用户体验:

首次web.png

支付失败重试

若买家支付失败,Antom 会根据具体的失败原因判断是否支持其在托管页面进行重试。买家重试支付的过程中,Antom 不会发送授权支付结果通知。只有买家支付成功或订单超时关闭后,您才会收到授权支付结果通知。买家重试支付的页面示例如下:

retry.png

当买家修改卡信息并重新提交后,Antom 将发起新的支付重试,以挽回交易并提升成功率。此时,商户侧的支付请求号 paymentRequestId 将对应多个 paymentId,对应场景如下表所示:

paymentRequestId

场景

商户侧 paymentRequestId_01

买家首次下单 pay(单笔支付)接口同步返回 paymentId_1

买家首次支付失败后返回托管页面重试支付,生成 paymentId_2

买家多次支付失败返回托管页面重试支付,生成 paymentId_N

注意:

  • 建议您存储最终授权结果异步通知中的 paymentId,用于处理后续的请款、退款、争议。
  • 如您仍使用首次调用 pay(单笔支付)接口时同步返回的 paymentId 发起请款或退款,Antom 可兼容并继续处理交易,但在响应、通知及账单中将返回买家重试产生的 paymentId,而非首次下单时返回的 paymentId。具体如下:

常见问题

问:如何处理 Antom 返回的卡信息采集链接(normalUrl)?

答:获取到卡信息采集链接(normalUrl)后,请根据您的客户端类型按以下方式处理:

  • 网页端(Web/WAP):直接引导买家跳转至该链接地址。
  • 应用程序(App):建议在应用内使用 WebView 组件加载该链接。

若交易需进行 3DS 认证,Antom 卡信息采集页面将自动重定向至发卡行认证页面,无需您进行额外处理。绝大多数发卡行的 3DS 认证流程为 H5 页面完成,但少数银行可能需拉起其官方应用进行认证。

问:支付结果页内容如何展示?

答:支付结果页必须根据服务端返回的结果进行渲染。切勿将 paymentRedirectUrl 固定为 “支付成功页面”,因为无论支付成功与否,都有可能从支付方式回跳到商户页面。

问:回跳商户结果页是否代表支付成功?

答:不能仅凭回跳商户页面来判定支付成功,主要原因如下:

  • 买家支付成功后,可能因网络等原因导致未能回跳至商户结果页;即使买家未完成支付,也可能通过支付方式端的入口回跳至商户结果页。
  • 为防范参数篡改等安全风险,Antom 不会在 paymentRedirectUrl 中拼接任何支付结果参数。

问:Antom 返回的 3DS 跳转链接是固定域名吗?
答:不是固定域名。Antom 返回的卡信息采集页域名为固定地址,但当交易需进行 3DS 认证时,会重定向至发卡行的认证页面,而不同发卡行的域名各不相同。请避免在 WebView 中设置跳转的白名单。

问:是否可以使用 iframe 加载 Antom 返回的卡信息采集链接(normalUrl)?

答:不建议使用 iframe 加载。Antom 返回的 normalUrl 为完整支付页面而非局部组件,内嵌框架会严重影响用户体验;同时,部分发卡行出于安全策略或兼容性限制,在 iframe 中可能无法正常展示或交互。

步骤 3:获取授权支付结果 服务端

授权支付成功或失败,或订单超时关闭后, Antom 会通过服务器交互将相应的授权支付结果发送给您,您可以通过以下方法之一获取授权支付结果:

  • 接收来自 Antom 的异步通知
  • 主动查询支付结果

接收异步通知

按照以下步骤接收并处理来自 Antom 的异步通知:

  1. 设置接收通知的 webhook URL

完成授权或授权失败时,Antom 会向您设置的 webhook URL 发送异步通知,您可以选择以下两种方法之一来设置接收通知的 webhook URL(若两者都设置,则以接口请求中指定的 URL 优先):

  • 若您的每个订单都有单独的通知 URL,建议您在每笔请求中设置 webhook URL。您可以在 pay(单笔支付)接口请求的 paymentNotifyUrl 参数传入该笔订单的异步通知接收 URL。
  • 若您的所有订单有统一的通知 URL,您可以在 Antom Dashboard > 开发者 > 通知地址 中设置 webhook URL。具体操作请参阅通知地址。

注意:

  • 若跳转 3DS 认证页面后买家未完成身份验证,则需要等待订单关闭后 Antom 才会发送授权支付结果异步通知,默认关单时间为 14 分钟。
  • 部分失败场景如参数异常等,pay(单笔支付)接口会在响应中同步返回 F,此时 Antom 不会发送异步通知。您可根据 F 状态直接关闭订单。

以下是异步通知请求体的代码示例:

{
    "actualPaymentAmount": {
        "currency": "EUR",
        "value": "7000"
    },
    "notifyType": "PAYMENT_RESULT",
    "paymentAmount": {
        "currency": "EUR",
        "value": "7000"
    },
    "paymentCreateTime": "2024-10-08T20:34:29-07:00",
    "paymentId": "20*********************96",
    "paymentRequestId": "PAY_20**********38",
    "paymentResultInfo": {
        "avsResultRaw": "",
        "cardBrand": "MASTERCARD",
        "cardNo": "41************54",
        "cvvResultRaw": "",
        "funding": "CREDIT",
        "issuingCountry": "CN",
        "paymentMethodRegion": "GLOBAL",
        "threeDSResult": {
            "cavv": "",
            "eci": ""
        }
    },
    "paymentTime": "2024-10-08T20:34:33-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

下表展示了授权支付结果的异步通知中 result.resultStatus 参数可能返回的值,请您根据指引进行处理:

result.resultStatus

信息

后续操作

S

授权支付成功。

可以发起请款,并储存 paymentId 用于请款或退款操作。

F

授权支付失败。

请关闭当前交易或更换 paymentRequestId 重新下单。

  1. 异步通知验签

当您收到 Antom 的异步通知,您需要按照返回收到确认信息的格式返回响应,但无需做加签处理。

您需要按照以下方法对 Antom 发送的支付通知进行验签:

import javax.servlet.http.HttpServletRequest;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import com.alipay.global.api.model.Result;
import com.alipay.global.api.model.ResultStatusType;
import com.alipay.global.api.response.AlipayResponse;
import com.alipay.global.api.tools.WebhookTool;

@RestController
public class PaymentNotifyHandleBySDK {

    /**
     * alipay public key, used to verify signature
     */
    private static final String SERVER_PUBLIC_KEY = "";

    /**
     * payment result notify processor
     * using <a href="https://spring.io">Spring Framework</a>
     *
     * @param request    HttpServletRequest
     * @param notifyBody notify body
     * @return
     */
    @PostMapping("/payNotify")
    public Object payNotifyHandler(HttpServletRequest request, @RequestBody String notifyBody) {

        // 从 HTTP 请求中获取所需的参数
        String requestUri = request.getRequestURI();
        String requestMethod = request.getMethod();

        // 从请求头中获取所需的参数
        String requestTime = request.getHeader("request-time");
        String clientId = request.getHeader("client-id");
        String signature = request.getHeader("signature");

        Result result;
        AlipayResponse response = new AlipayResponse();

        try {
            // 验签
            boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, SERVER_PUBLIC_KEY);
            if (!verifyResult) {
                throw new RuntimeException("Invalid notify signature");
            }

            // 反序列化通知体

            // 根据通知结果更新订单状态

            // 向服务器响应已接收通知
            result = new Result("SUCCESS", "success", ResultStatusType.S);

        } catch (Exception e) {
            String errorMsg = e.getMessage();
            // 处理错误情况
            result = new Result("ERROR", errorMsg, ResultStatusType.F);
        }
        response.setResult(result);
        return ResponseEntity.ok().body(response);
    }

}

无论订单是否支付成功,每个通知请求均需按以下固定格式响应。否则,Antom 会重新发送异步通知。

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

常见问题

问:什么时候会发送异步通知?

答:这取决于授权支付是否完成:

  • 如果支付成功完成,Antom 通常会在 3 到 5 秒内发送异步通知。
  • 如果支付未完成,Antom 需要先关闭订单,然后发送异步通知。不同支付方式关闭订单所需的时间会有所不同,通常默认为 14 分钟。

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

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

  • 由于网络原因未收到异步通知。
  • 如果收到来自 Antom 的异步通知,但您没有按照返回收到确认信息的格式进行响应。

通知最多可以重发 8 次,直到收到正确的响应以终止传递。异步通知的发送间隔为:0 分钟、2 分钟、10 分钟、10 分钟、1 小时、2 小时、6 小时和 15 小时。

问:在响应异步通知时,需要添加签名吗?

答:不需要。如果您收到 Antom 的异步通知,您需要按照返回收到确认信息的格式返回响应,但无需做加签处理。

问:收到授权支付结果通知是否需要验签?

答:需要。通过验签以保障该请求是由 Antom 发送给您的。验签时,待验签报文的拼装格式必须严格遵循标准:<http-method> <http-uri> <client-id>.<request-time>.<request-body>。对于 <request-body> 部分,必须使用其原始的、未经任何处理的字符串值进行拼装。

问:是否可以依据异步通知中 resultStatus 的值为 S 来判断发货?

答:不可以。卡支付方式分为授权-请款两个阶段,异步通知中 resultStatus 的值仅代表授权结果,需根据请款结果来决策发货。

主动查询结果

除了通过异步通知获取授权支付结果,您还可以调用 inquiryPayment 接口主动查询授权支付结果,使用支付中的 paymentRequestId 查询支付状态。

以下代码展示了如何调用 inquiryPayment 接口:

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

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

{
  "paymentRequestId": "paymentRequestId01"
}

以下代码展示了一个响应报文的示例:

{
    "actualPaymentAmount": {
        "currency": "USD",
        "value": "5000"
    },
    "authExpiryTime": "2024-12-17T21:56:56-08:00",
    "cardInfo": {
        "cardBrand": "VISA",
        "funding": "CREDIT",
        "issuingCountry": "US"
    },
    "paymentAmount": {
        "currency": "USD",
        "value": "5000"
    },
    "paymentId": "20************56",
    "paymentMethodType": "CARD",
    "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=amsdmpay_yanfei_wzh_20240111_191505_666",
    "paymentRequestId": "paymentRequestId01",
    "paymentResultCode": "SUCCESS",
    "paymentResultInfo": {
        "avsResultRaw": "M",
        "cardBrand": "VISA",
        "cardNo": "************9954",
        "cvvResultRaw": "U",
        "funding": "CREDIT",
        "issuingCountry": "US",
        "networkTransactionId": "12********ew",
        "paymentMethodRegion": "GLOBAL",
        "threeDSResult": {
            "cavv": "",
            "eci": ""
        }
    },
    "paymentResultMessage": "success.",
    "paymentStatus": "SUCCESS",
    "paymentTime": "2024-12-10T21:56:57-08:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

请根据响应中 paymentStatus 参数的值进行处理,具体返回值请参阅接口文档。

常见问题

问:我在查询授权支付结果时需要注意哪些关键参数?

答:请注意以下关键参数:

  • paymentStatus: 您需要根据此参数来判断授权支付状态。
  • paymentAmount:表示支付的金额,可用于金额核对。
  • result:仅表示本次 inquiryPayment 接口的调用结果。订单的授权结果需根据 paymentStatus 的值进行判断,SUCCESS和 FAIL 表示支付终态结果,PROCESSING 表示处理中。

问:建议发起查询的频率是多久?

答:推荐以轮询的形式发起查询,间隔 2 秒。从发起 pay(单笔支付)接口请求后立即发起轮询,直到查询到最终的支付结果或收到支付结果异步通知为止。

步骤 4:获取请款结果 服务端

授权支付成功后,Antom 默认自动为您请款,同时支持您手动发起请款。请款后,您可以通过异步通知或主动查询来获取请款结果,您需要根据请款结果来决定是否发货。具体操作请参阅请款。

支付后操作

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

取消交易 服务端

在卡支付场景中,Antom 支持以下三种情况下的撤销操作:

  • 由 Antom 为您自动请款时,对于授权通知成功但请款通知失败的交易,Antom 会在 7 天后发起撤销;您也可以主动发起撤销,避免买家资金被冻结 7 天。
  • 由您手动请款时,对于授权成功的订单,若您判断无需发起请款,则可以调用 cancel 接口,释放买家的冻结资金。
  • 对于未完成授权的交易,为避免重复扣费,您可调用 cancel 接口取消交易。

请参阅取消交易了解更多内容。

常见问题

问:订单请款成功后,是否还能发起撤销?

答:不能。订单一旦请款成功,无法再进行撤销。如需处理该订单资金,请发起退款。具体流程请参考订单生命周期。

问:订单授权支付成功后若不请款,会自动撤销吗?

答:会的。订单授权成功后,最晚在 7 天内需要发起请款,否则 Antom 将自动撤销该订单以解冻资金,无需您额外调用 cancel 接口。同时,为避免买家资金被冻结 7 天,建议您主动调用 cancel 接口为买家提前释放资金。

退款 服务端

不同支付方式的退款能力各有差异,若您需要了解 Antom 的退款规则及如何对成功的交易发起退款,请参阅退款。

争议 服务端

当某笔交易发生争议时,Antom 为您提供争议处理相关服务。更多信息请参阅争议运营手册和争议实施方案。

卡支付特性

托管模式支持以下卡支付特性,点击了解不同特性的具体信息及使用方法: