APM 支付

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

本文主要阐述了 APM 类支付方式如何通过 API 方式进行集成。

支付体验

一种基于独立账户体系的电子支付解决方案。通过电子钱包账户,买家可轻松完成线上购物或线下消费支付,实现高效、安全、便捷的支付体验。

电子钱包.png

支付流程

各类支付方式的支付流程由以下集成步骤组成:

APO-APM流程图.png

  1. 买家进入支付方式选择页面
  2. 创建支付请求
    买家选择支付方式并提交订单后,商户服务端根据支付方式、金额、币种、商品等交易信息,调用 支付 接口以发起支付请求
  3. 处理支付推进链接
    商户客户端跳转至支付请求返回的 URL 页面,或唤起相关应用程序完成支付。支付推进链接根据支付方式的特性执行不同的操作,如收集信息、重定向买家、调用应用、显示二维码和进行验证。
  4. 获取支付结果
    商户服务端接收 APO 返回的支付结果通知,并根据结果进行相应的业务处理。

注意:在 PayPal 和 Pay by bank 支付场景下,采用的是授权请款模式。步骤 1 至 4 仅完成了授权部分,即买家完成支付后,其资金处于冻结状态。为了将买家的冻结资金转至您的账户,您还需要集成请款步骤。请款成功的结果将作为您发货的依据。


注意:若您在多机构下开通了同一个支付方式,请在 APO Dashboard 完成路由配置。若不配置,则 APO 会采取随机路由规则。

集成准备

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

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

集成步骤

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

  1. 添加支付方式列表
  2. 创建支付订单
  3. 获取跳转支付推进链接
  4. 接收异步通知

步骤1:添加支付方式列表 客户端

在买家下单页面的支付方式列表中,展示本次需要集成的支付方式标识和名称供买家根据自身需求和偏好选择。可通过品牌资产自助获取支付方式的标识和名称。如遇部分支付方式无法在线获取,请联系技术支持协助获取。

注意:支付方式列表页面需要您自行实现。

步骤2:创建支付请求 服务端

当买家选择支付方式点击支付时,您需要调用 支付 接口来收集买家的支付方式、订单信息、设备信息、支付金额等提交支付请求。

调用接口时注意以下关键参数:

参数名称

是否必需

描述

productCode

在此场景中,该字段设置为 CASHIER_PAYMENT

paymentRequestId

商户生成的专属 ID,每次发起支付需要生成新的 ID。

paymentAmount

支付金额,需按下单币种的最小单位设置,如 CNY 为分,KRW 为元。

paymentMethod

支付方式枚举值。

paymentRedirectUrl

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

paymentNotifyUrl

支付结果通知地址,可通过接口指定或在 APO Dashboard 里设置一个固定值。

settlementStrategy

支付请求的结算策略。若业务签约了多个结算币种,则需在接口中指定 settlementCurrency 参数。该参数仅对 Antom 收单机构生效。

order

包括订单金额、订单 ID 和订单描述的订单信息。

当支付方式为 PayPal 时,请注意以下几个子字段:

  • order.goods必传,goods 里的所有金额之和需要和 paymentAmountorderAmount 金额保持一致,否则 PayPal 会拒绝该笔交易。
  • order.shipping必传,虚拟产品不需要传。

env.terminalType

买家发起交易的环境:

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

env.osType

买家发起交易的环境。当在商户手机浏览器网站发起,则 env.osType 为 ANDROID 或者 IOS

env.browserInfo.language

指定用户浏览器的语言。如果不传入则默认为英文。

注意:当支付方式为 PayPal 时,该参数必传。

paymentFactor.isAuthorization

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

  • false:默认值。表示支付场景为常规支付,无需授权。对于 APM 支付,除 PayPal 和 Pay by bank 以外,其他支付方式都需将参数的值设为 false 或置空以避免资金被自动解冻并返回给用户。
  • true:表示支付场景为授权场景。当 paymentMethodType 的值为 PAYPAL  ONLINEBANKING_YAPILY 时,请将此参数的值设为 true
paymentFactor.captureMode

表明授权支付后资金的扣款方式。有效值如下:

  • AUTOMATIC:表示授权后,Antom 自动扣款。当值为空或未传入此参数时,情况相同。
  • MANUAL:表示需要通过调用 请款 接口手动扣款。

注意:APM 支付场景下,当且仅当 paymentMethodTypeONLINEBANKING_YAPILY 需要设置为 AUTOMATIC

paymentMethod.paymentMethodMetaData.bankIdentifierCode

银行的唯一代码。

注意:APM 支付场景下,当且仅当 paymentMethodTypeONLINEBANKING_YAPILY 需要传入此参数。

有关完整参数的更多信息,请参阅 支付 接口。

以下代码为调用 支付 接口以发起支付请求的示例:

copy
public static void executePayWithCard() {
        AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
        alipayPayRequest.setClientId(CLIENT_ID);
        alipayPayRequest.setPath("/ams/api/v1/payments/pay");
        alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

        // 替换为您的 paymentRequestId
        alipayPayRequest.setPaymentRequestId("paymentRequestId01");

        // 设置 amount
        Amount amount = new Amount();
        amount.setCurrency("HKD");
        amount.setValue("100");
        alipayPayRequest.setPaymentAmount(amount);

        // 设置 paymentMethod
        PaymentMethod paymentMethod = new PaymentMethod();
        paymentMethod.setPaymentMethodType("ALIPAY_HK");
        alipayPayRequest.setPaymentMethod(paymentMethod);

        // 设置 order 信息
        Order order = new Order();
        order.setReferenceOrderId("referenceOrderId01");
        order.setOrderDescription("antom test order");
        order.setOrderAmount(amount);
        alipayPayRequest.setOrder(order);

        //设置 env 信息
        Env env = new Env();
        env.setTerminalType(TerminalType.WAP);
        env.setClientIp("114.121.121.01");
        env.setOsType(OsType.ANDROID);
        alipayPayRequest.setEnv(env);

        // 替换为您的 notifyUrl
        alipayPayRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com");

        // 替换为您的 redirectUrl
        alipayPayRequest.setPaymentRedirectUrl("http://www.yourRedirectUrl.com");

        //进行支付
        AlipayPayResponse alipayPayResponse = null;
        try {
          alipayPayResponse = defaultAlipayClient.execute(alipayPayRequest);
        } catch (AlipayApiException e) {
          String errorMsg = e.getMessage();
          // 处理错误情况
        }
    }

以下代码显示了请求报文的示例:

copy
{
  "paymentNotifyUrl": "http://www.yourNotifyUrl.com",
  "paymentRequestId": "paymentRequestId01",
  "env": {
    "terminalType": "WAP",
    "clientIp": "114.121.121.01",
    "osType": "ANDROID"
  },
  "paymentAmount": {
    "currency": "MYR",
    "value": "230"
  },
  "productCode": "CASHIER_PAYMENT",
  "paymentRedirectUrl": "http://www.yourRedirectUrl.com",
  "paymentMethod": {
    "paymentMethodType": "BOOST"
  },
  "order": {
    "orderAmount": {
      "currency": "MYR",
      "value": "230"
    },
    "referenceOrderId": "referenceOrderId01",
    "orderDescription": "antom test order"
  }
}

响应代码中涉及以下关键参数:

字段名

建议消费方式

result.resultStatus

判断支付状态。

normalUrl

需跳转 WAP 类型支付的链接。

applinkUrl

需跳转 deeplink 类型支付链接。

schemeUrl

需跳转 scheme 类型支付链接。

以下代码显示了响应报文的示例:

copy
{
    "acquirerInfo": {
        "acquirerMerchantId": "2188120040699147",
        "acquirerName": "ALIPAY",
        "acquirerResultCode": "PAYMENT_IN_PROCESS",
        "acquirerResultMessage": "Payment is processing.",
        "acquirerTransactionId": "20250425194010800100188820290660379",
        "referenceRequestId": "PAYMENT_20250425100955370_AUTO"
    },
    "appIdentifier": "my.com.myboost",
    "applinkUrl": "https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr",
    "normalUrl": "https://msp.boost-my.com/onlinepayment/authorise?source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr",
    "orderCodeForm": {
        "codeDetails": [
            {
                "codeValue": "https://global.alipay.com/28100204009zSetrzUJKN49jpb2sf4m6IgNr",
                "displayType": "TEXT"
            },
            {
                "codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr&picSize=L",
                "displayType": "BIGIMAGE"
            },
            {
                "codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr&picSize=M",
                "displayType": "MIDDLEIMAGE"
            },
            {
                "codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr&picSize=S",
                "displayType": "SMALLIMAGE"
            }
        ],
        "expireTime": "2025-04-24T19:23:55-07:00"
    },
    "paymentActionForm": "{\"method\":\"GET\",\"paymentActionFormType\":\"RedirectActionForm\",\"redirectUrl\":\"https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr\"}",
    "paymentAmount": {
        "currency": "MYR",
        "value": "230"
    },
    "paymentCreateTime": "2025-04-24T19:09:56-07:00",
    "paymentId": "20250425194010800100188820290660379",
    "paymentRequestId": "PAYMENT_20250425100955370_AUTO",
    "redirectActionForm": {
        "method": "GET",
        "redirectUrl": "https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr"
    },
    "schemeUrl": "boostapp://inAppDeeplink?deeplink_path=deeplink/onetimepayment&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F28100204009zSetrzUJKN49jpb2sf4m6IgNr",
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process",
        "resultStatus": "U"
    }
}

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

result.resultStatus

信息

后续操作

S

支付成功。

无需进一步操作。

F

支付失败。关闭当前交易订单或重新更换 paymentRequestId 后再次发起支付请求

U

未知原因。

  • 若返回 PAYMENT_IN_PROCESS 结果码,获取任意一个链接 (applinkUrl/normalUrl/schemeUrl) 并打开收银页面。
  • 若返回其他结果码,关闭当前交易订单或重新更换 paymentRequestId 后再次发起支付请求

注意:如果您未收到响应报文,可能是网络超时所致。关闭当前交易订单或重新更换 paymentRequestId 后再次发起支付请求。

常见问题

问:如何确认响应代码中需要消费的 URL 类型?

答:不同支付方式在不同端类型下,APO 可能会返回以下三种 URL 中的一种或多种:normalUrlapplinkUrlschemeUrl。商户服务端需将这些 URL 传递给商户前端,可以选择任选一种 URL 进行跳转消费。

问:什么是 paymentId

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

问:如何设置 terminalType

答:terminalType 的有效值为:

  • WEB: 让买家在 PC 端发起交易。
  • WAP: 让买家在移动浏览器上发起交易。当 terminalType 指定为 WAP 时需添加 osType 参数,并根据买家的手机填写相应的系统参数 ANDROIDIOS
  • APP: 让买家在应用内发起交易。

问:什么是 acquirerInfo

答:acquirerInfo 返回对应的收单机构及收单机构侧的单据信息,包括:

  • acquirerName:收单机构名称。
  • referenceRequestId:APO 请求收单机构的单号。
  • acquirerTransactionId:收单机构单号。

若您需要使用收单机构账单,那么您需要存储该字段用于后续对账使用。具体信息请查看单号说明文档。

步骤 3:获取跳转支付推进链接 客户端

商户服务端拿到 APO 返回的支付推进链接后,将该地址传递给前端,由商户前端跳转至支付方式页面。不同类型的支付推进链接如下表所示:

类型

描述

示例 URL

normalUrl

一个 HTTPS 地址的链接,用于在同一浏览器页面上重定向到支付方式的网站页面。

URL=serverResponse.normal

applinkUrl

在支付过程中用于重定向的 Android App Link 或 iOS Universal Link。

URL=serverResponse.applink

schemeUrl

用于打开支付方式应用的 URL scheme。

URL=serverResponse.scheme

请参阅支付推进链接使用最佳实践了解更多内容。

以下为商户前端加载支付推进链接的示例代码:

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

下图为支付方式收银台页面展示

image.png

不同支付方式的不同端会返回不同的支付推进链接,APO 会基于商户传入的 paymentMethodterminalType 决策返回不同的支付推进链接类型。详情请参阅支付推进链接使用最佳实践

下表列举了不同终端返回的支付推进链接类型及其用户体验。关于具体的不同支付方式返回的支付推进链接,请参阅支付方式返回链接了解更多详情。

支付推进链接

功能

用户体验

applinkUrl

  • 买家已安装支付方式应用程序时可拉起应用程序。
  • 买家未安装支付方式应用程序时可拉起 WAP 页面。
  • 可以自动判断买家是否安装支付方式应用程序。
  • 一般在买家商户应用程序或手机网站发起支付时会返回该 URL,具体依赖于支付方式是否支持。
  • 买家已安装支付方式应用程序

image.png

  • 买家未安装支付方式应用程序

image.png

schemeUrl

  • 通过支付方式应用程序的 scheme 直接拉起应用程序。
  • 买家未安装支付方式应用程序时无法拉起且会显示异常,请参阅支付推进链接使用最佳实践了解更多详情。
  • 一般在买家商户应用程序或手机网站发起支付时会返回该 URL,具体依赖于支付方式是否支持。
  • 买家已安装支付方式应用程序

image.png

  • 买家未安装支付方式应用程序:不支持

normalUrl

  • 支付方式的 WAP (H5) 页面。
  • 不同支付方式的 WAP (H5) 页面体验不同,部分支付方式支持登录后直接支付,还有部分支付方式需要中间页拉起支付方式应用程序后进行支付。
  • 买家从商户 Web 端发起支付时,均返回此 URL,具体依赖于支付方式是否支持。
  • Web 端交易:

image.png

  • WAP 端交易

image.png

  • 中间页拉起支付方式应用程序

image.png

常见问题

问:如何处理不同的支付体验?

答:根据不同的支付推进链接,支付体验会有所差异。schemeUrl直接跳转至支付方式的应用程序完成支付,而其他 URL 则仅支持在 WAP (H5) 页面内完成支付。详情请参与支付推进链接使用最佳实践

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

答:您需要通过在 支付 接口中指定 paymentRedirectUrl 字段来提供一个 HTTPS 地址。该地址用于在商户端显示支付结果。展示支付结果页时需注意以下事项:

  • 支付成功和支付失败的情况下,可能都有入口可以从支付方式端回跳到商户页面。因此,请勿将 paymentRedirectUrl 固定为“支付成功页面”,而是以服务端返回的结果为准,避免引起买家误解。
  • 如果商户从应用程序端发起交易,则需将 paymentRedirectUrl 设置为商户应用程序的 scheme 地址。
问:回跳至商户结果页面是否代表支付成功?

答:不能仅凭回跳至商户页面来判断支付是否成功,可能存在以下情况导致回跳商户页失败:

  • 买家支付成功后,可能因网络等原因导致未能回跳至商户页面。
  • 当买家未完成支付时,也可能通过支付方式端的入口回跳至商户页面。
  • APO 不会在 paymentRedirectUrl 拼接表示支付结果的字段信息。

步骤 4:接收异步通知 服务端

完成支付或支付失败时,APO 会通过 支付 接口中的参数 paymentNotifyUrl 指定的地址发送异步通知支付通知)。

  1. 您可以选择以下两种方法中的一种来设置接收通知的地址:
    • 若您的每个订单都有单独的通知 URL,建议在每笔请求中设置通知 URL。您可以通过 支付 接口请求的 paymentNotifyUrl 字段中传入该笔订单的异步通知接收地址。
    • 若您的所有订单有统一的通知 URL,您可以在 APO Dashboard 开发者 通知地址中设置通知 URL。具体操作请参阅通知地址

注意:如果请求和 APO Dashboard 中都指定了链接,则请求中的值优先。

支付通知中涉及以下关键参数:

参数名称

是否必需

描述

resultStatus

表示订单支付结果的状态。

paymentRequestId

商户发起支付的唯一 ID。

paymentAmount

表示支付金额。

有关完整参数的更多信息,请参阅 支付通知

以下是支付结果异步通知请求的代码示例:

copy
{
  "acquirerInfo": {
    "acquirerMerchantId": "2188120156094843",
    "acquirerName": "ALIPAY",
    "acquirerResultCode": "SUCCESS",
    "acquirerResultMessage": "success",
    "acquirerTransactionId": "20250424194010800100188500290131480",
    "referenceRequestId": "G153202504250530363913"
  },
  "actualPaymentAmount": {
    "currency": "HKD",
    "value": "3800"
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "HKD",
    "value": "3800"
  },
  "paymentCreateTime": "2025-04-24T14:30:37-07:00",
  "paymentId": "20250424194010800100188500290131480",
  "paymentRequestId": "G153202504250530363913",
  "paymentResultInfo": {},
  "paymentTime": "2025-04-24T14:31:19-07:00",
  "pspCustomerInfo": {
    "pspCustomerId": "2160220157151232",
    "pspName": "ALIPAY_HK"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

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

result.resultStatus

信息

后续操作

S

支付成功。

可从中获取以下字段信息:

  • paymentId:表示由 APO 生成的支付订单 ID,用于退款和取消交易。

F

支付失败。

关闭当前交易订单或更换 paymentRequestId 后再次发起支付请求。

注意:部分失败场景,如参数异常等,支付 接口会同步返回 F,不会发送异步通知,您可以根据 F 状态直接关闭订单。

  1. APO 发送的通知结果由 APO 加签,故建议您验证签名以确认通知由 APO 发送。参考以下代码示例对支付通知进行验签:
copy
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);
    }
}
  1. 收到通知后,您无需对响应通知结果做加签处理,但是对于每个通知请求均需按以下固定格式响应,与订单支付成功与否无关。否则,APO 会重新发送异步通知。
copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    }
}

常见问题

问:何时会发送支付结果通知?

答:这取决于支付是否完成。如果支付完成后,在收到收单机构的通知后 APO 会立即发送异步通知。

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

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

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

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

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

答:如果您收到来自 APO 的异步通知,您需要按照处理通知的示例代码格式返回响应,但不需要对响应进行签名。

问:异步通知里返回 acquirerInfo 的信息作用是什么?
答:acquirerInfo 里包含了收单机构的信息,如收单机构名称、收单机构侧单号等。建议您存储该信息用于后续账单等使用具体原因请查看单号说明

支付后操作

以下内容将介绍支付后如何通过服务端主动查询交易状态、发起交易取消以及退款操作的具体方法,帮助您实现稳定可靠的支付管理体验。

查询交易 服务端

APO 提供发送异步通知的功能,同时也支持主动查询支付结果。调用 支付结果查询 接口,通过以下参数查询支付结果:

参数名称

是否必需

描述

paymentRequestId

商户生成的支付请求 ID。

有关完整参数的更多信息,请参阅 支付结果查询 接口

以下为调用 支付结果查询 接口的代码示例:

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

以下为请求示例:

copy
{
    "paymentRequestId": "G153202504250530363913"
}

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

copy
{
  "acquirerInfo": {
    "acquirerMerchantId": "2188120156094843",
    "acquirerName": "ALIPAY",
    "acquirerResultCode": "SUCCESS",
    "acquirerResultMessage": "success",
    "acquirerTransactionId": "20250424194010800100188500290131480",
    "referenceRequestId": "G153202504250530363913"
  },
  "actualPaymentAmount": {
    "currency": "HKD",
    "value": "3800"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "3800"
  },
  "paymentId": "20250424194010800100188500290131480",
  "paymentMethodType": "ALIPAY_HK",
  "paymentRedirectUrl": "https://alipay.kurogame-service.com/web-alipay/result?lang=zh-Hant",
  "paymentRequestId": "G153202504250530363913",
  "paymentResultCode": "SUCCESS",
  "paymentResultMessage": "success.",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2025-04-24T14:31:19-07:00",
  "pspCustomerInfo": {
    "pspName": "ALIPAY_HK"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

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

paymentStatus

描述

后续操作

SUCCESS

支付成功。

无需后续操作。

FAIL

支付失败。

关闭订单或更换 paymentRequestId 再次发起请求。

PROCESSING

支付进行中。

建议等待一段时间后继续查询状态或关闭订单再重新查询。

常见问题

问:调用 支付结果查询 接口时应该消费哪些字段?

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

  • result:表示接口调用的结果,需要根据 paymentStatus 来判断订单状态:
    • SUCCESSFAIL 表示最终支付结果。
    • PROCESSING 表示处理中。
  • paymentAmount:表示支付的金额,用于核对交易金额。

问:发起查询的推荐间隔是多久?

答:推荐以轮询的形式调用 支付结果查询 接口,间隔 2 秒,直到获取最终的支付结果或收到异步支付结果通知为止。

取消交易 服务端

对于支付成功后的订单,如果买家在当天内申请取消订单或退款,您可以通过 APO 提供的取消支付能力将订单状态取消或解冻。此外,对于尚未完成支付的订单,您也可以直接进行取消。请参阅取消交易了解关于取消支付集成方案的更多内容。

退款 服务端

在支付成功后,如果买家申请退款,您可以参考退款文档完成退款。

支付方式特性

本部分内容旨在系统阐述各类支付方式在支持特性方面的差异。

取消交易能力

不同支付方式的取消交易窗口期有差异,Antom 下各支付方式详情请参阅取消交易

退款能力

不同支付方式的退款能力不同,主要为能否支持退款和支持退款的周期。Antom 下各支付方式的退款能力详情请参阅支持的支付方式

默认关单时间

Antom 下各支付方式的关单详情请参阅默认关单时间

其他支付方式特性

收单机构

支付方式

特性

建议方案

Antom

PayPay

paymentRedirectUrl 字段长度。

paymentRedirectUrl 不超过255个长度。

Antom

PayPay

退款次数不能超过 20 次。

Antom

SOFORT

支付成功先发 PAYMENT_PENDING通知,待渠道受理完成再发PAYMENT_RESULT 通知。

由商户决策是否在收到PAYMENT_PENDING 先发货。

Antom

SOFORT

PAYMENT_PENDING 状态无法退款。

PAYMENT_PENDING 状态只能取消交易,PAYMENT_RESULT 状态下可以退款。

Antom

Maybank

支付完成后通知延迟 5 分钟。

给买家展示订单确认中的状态提示。

Antom

OVO

Pix

BANCOMAT Pay

无法自动拉起钱包。

手动拉起钱包完成支付。

Antom

Siam Commercial Bank(网银支付)

支付有手续费。

提示买家可能存在支付手续费(费用由买家在银行的等级决定)。

Antom

Bank of Ayudhya

支付有手续费。

提示买家可能存在支付手续费(费用由买家在银行的等级决定)。

Antom

GoPay(印度尼西亚)

Bangkok Bank(移动端)

Siam Commercial Bank(移动端)

Bank of Ayudhya(移动端)

Krungthai Bank(移动端)

不支持 PC 端。

Antom

NAVER Pay

PC 端需额外集成;

买家登录后非原页面支付重定向,而是自动新开 tab 页重定向。

开启允许弹窗设置并单独开启一个 browser 对象打开新的弹窗页面。

Antom

Mercado Pago(巴西)

会消费 buyerEmail 导致支付直接失败。

建议传入 payerEmail。

Antom

Express Bank Transfer

应用程序端传入的paymentRedirectUrl 不能包含 & 符号,否则不能回跳。

使用其他符号代替。

最佳实践

为了提高集成效率,APO 为您提供客户端优化、回跳商户页展示、支付失败重试、接口超时时间设置、中间页优化等最佳实践方案,请参阅最佳实践了解详情。