Antom, leading provider of tailored payment solutions

Checkout Page 集成

本篇介绍如何通过 Checkout Page 集成来授权 Pix Automático 并提交首次支付。

用户体验

下图展示了授权流程及首次支付的用户体验:
Web
扫描二维码支付:
使用支付码支付:
Mobile

授权及首次支付流程

授权及首次支付流程分为以下步骤:

集成准备

在您开始集成前,请阅读集成指南及接口概述文档,了解服务端接口的集成步骤及调用接口的注意事项,并确保已完成以下预配置:
  • 已获得 client ID。
  • 已完成密钥配置。
  • 已完成异步通知接收地址的配置。
  • 集成服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。

集成步骤

  1. 发起授权和首次支付请求
  2. 跳转到 normalUrl
  3. 获取授权结果
  4. 获取首次支付结果

步骤 1:发起授权和首次支付请求
服务端

调用 createPaymentSession(单笔支付)接口来发起授权和首次支付请求。以下是重点参数:
参数名
是否必需
描述
subscriptionInfo.allowRetry
否
表示当订阅扣款因余额不足而失败时是否允许您发起重试。有效值为:
  • true:表示当订阅扣款因余额不足而失败时允许您发起重试。
  • false:默认值。表示当订阅扣款因余额不足而失败时不允许您发起重试。
subscriptionInfo.retryMode
否
重试模式。有效值为:
  • MANUAL:默认值。如果您有自己的调度或催收系统,请选择此值。详情请参考商户发起扣款重试。
subscriptionInfo.subscriptionDescription
是
订阅的描述,用于显示用户消费记录及进行其他操作。
subscriptionInfo.subscriptionStartTime
是
订阅生效的日期和时间。​
注意:订阅生效时间至少为未来 48 小时。
subscriptionInfo.periodRule.periodType
是
此字段仅用于 Pix Automático 订阅扣款场景。 有效值为:
  • WEEK:表示订阅周期以周为单位。
  • MONTH:表示订阅周期以月为单位。
  • QUARTER:表示订阅周期以季为单位。
  • HALF_YEAR:表示订阅周期以半年为单位。
  • YEAR:表示订阅周期以年为单位。
subscriptionInfo.periodRule.periodCount
是
一个订阅周期内周期类型的数量。
subscriptionInfo.subscriptionNotifyUrl
是
用于接收订阅结果通知的地址。
order.orderAmount
是
折扣或税费应用前的订单总额。此参数的值会显示在用户消费记录或支付结果页面上。
order.referenceOrderId
是
在商户端识别订单的专属 ID,由直接向客户提供服务或商品的商户分配。
order.orderDescription
是
订单的简要描述。
paymentRequestId
是
商户为识别支付请求而分配的专属 ID。
paymentAmount
否
代表首次支付向用户收取的支付金额。
注意:折扣的场景下要求传入折后最终值。
settlementStrategy.settlementCurrency
是
商户希望结算的币种的 ISO 币种代码。如果商户注册了多种币种结算,此字段是必需的。
paymentMethod.paymentMethodType
是
设置此参数的值为 PIX_AUTOMATICO。
paymentMethod.paymentMethodMetaData.maxAmountFloor
否
该值表示商家在后续周期扣款中可向用户收取金额的最低值。
注意:
  • 用户可在 app 设置中设定该授权的最高扣款金额,但不得低于商户设定的 maxAmountFloor。示例:如果商家设置为 100 BRL,而用户在 app 中将最高抵扣金额设为 200 BRL,则商家在后续扣款时只能扣除 100 至 200 BRL 之间的金额。
  • 此字段仅用于 Pix Automático 定期扣款场景。
paymentMethodMetaData.fixedAmount.currency
否
固定订阅金额币种。币种代码,值为遵循 ISO 4217 标准的三位币种代码。
paymentMethodMetaData.fixedAmount.value
否
固定订阅金额币种。
paymentRedirectUrl
是
支付完成后用户被重定向到的商户页面链接。
productCode
是
表示合同中规定的正在使用的支付产品。对于单笔支付,值设置为 CASHIER_PAYMENT。
完整参数和额外要求请参考 createPaymentSession(单笔支付)接口。
以下示例代码展示了如何调用 createPaymentSession(单笔支付)接口:
public static void createPaymentSession() {
  AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
  alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
  alipayPaymentSessionRequest.setProductScene(ProductSceneConstants.CHECKOUT_PAYMENT);

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

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

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

  // 设置金额
  // amount.value 等于 goodsAmount.value * goods.goodsQuantity
  // 有关支付方式支持的币种,请参阅:<a href="https://docs.antom.com/ac/pm/supported_pm">支持的支付方式</a>
  Amount amount = Amount.builder().currency("BRL").value("6000").build();
  alipayPaymentSessionRequest.setPaymentAmount(amount);

  // 设置订单信息
  // 注意,order.orderAmount、order.referenceOrderId 和 order.orderDescription 为必填项
  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);

  // 替换为你的通知 URL
  // 或在此处配置你的通知 URL:<a href="https://dashboard.antom.com/global-payments/developers/iNotify">通知 URL</a>
  alipayPaymentSessionRequest.setPaymentNotifyUrl(
    "http://www.yourNotifyUrl.com/payment/receiveNotify"
  );
  // 替换为你的重定向 URL
  alipayPaymentSessionRequest.setPaymentRedirectUrl(
    "http://localhost:8080/index.html?paymentRequestId=" + paymentRequestId
  );

  AlipayPaymentSessionResponse alipayPaymentSessionResponse;
  try {
    System.out.println(JSON.toJSONString(alipayPaymentSessionRequest));
    alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
  } catch (AlipayApiException e) {
    String errorMsg = e.getMessage();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
{
    "productCode": "CASHIER_PAYMENT",
    "productScene": "CHECKOUT_PAYMENT",
    "order": {
        "orderAmount": {
            "currency": "BRL",
            "value": "100"
        },
        "referenceOrderId": "ORDER_12345678900",
        "orderDescription": "ANTOM_ZZ"
    },
    "paymentMethod": {
        "paymentMethodType": "PIX_AUTOMATICO",
        "paymentMethodMetaData": {
            "cpf": "02859464980",
            "fullName": "full name",
            "maxAmountFloor": {
              "currency": "BRL",
              "value": "100"
            }
          }
        }
    },
    "paymentAmount": {
        "currency": "BRL",
        "value": "100"
    },
    "settlementStrategy": {
        "settlementCurrency": "SGD"
    },
    "subscriptionInfo": {
        "periodRule": {
            "periodCount": 1,
            "periodType": "MONTH"
        },
        "allowRetry": true,
        "retryMode": "MANUAL",
        "subscriptionDescription": "Monthly Subscribe",
        "subscriptionRedirectUrl": "https://www.alipay.com",
        "subscriptionNotifyUrl": "https://api.joyland.ai/pay/antom/subscription/webhook",
        "subscriptionStartTime": "2026-01-16T10:22:52-03:00",
        "subscriptionEndTime": "2035-02-24T14:55:16-03:00"
    },
    "paymentNotifyUrl": "https://www.example.com/notify",
    "paymentRequestId": "PAYMENT_20260115184454498_AUTO",
    "paymentRedirectUrl": "https://www.example.com/result"
}
以下代码展示了一个响应的示例:
{
  "normalUrl": "https://checkout.antom.com/checkout-page/pages/payment/index.html?sessionData=p7uxRxyjzPZv7RaxS8YXirX7n9HxgZLArhnvRvNXiEkIefZbPs72GoLnKObmOWjbW%2Fl86np%2FSywT9JjZli7MOw%3D%3D%26%26US%26%26188%26%26eyJlbGlnaWJsZUVhc3lQYXlNYXJrZXRpbmciOmZhbHNlLCJleHRlbmRJbmZvIjoie1wiT1BFTl9NVUxUSV9QQVlNRU5UX0FCSUxJVFlcIjpcImZhbHNlXCIsXCJkaXNwbGF5TGF5b3V0XCI6XCJMRUZUX09SREVSX0FORF9SSUdIVF9QQVlNRU5UXCIsXCJ0aGVtZVR5cGVcIjpcIkxJR0hUXCIsXCJkaXNwbGF5QW50b21Mb2dvXCI6XCJ0cnVlXCJ9IiwibmVlZEFjY291bnRDb25maXJtUGFnZSI6ZmFsc2UsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBTEwiLCJwcm9kdWN0U2NlbmUiOiJDSEVDS09VVF9QQVlNRU5UIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJzZWN1cml0eUNvbmZpZyI6eyJhcHBJZCI6IiIsImFwcE5hbWUiOiJPbmVBY2NvdW50IiwiYml6VG9rZW4iOiI2VGNkYnIyckYzclBZeDRoa1ZySHFidmoiLCJnYXRld2F5IjoiaHR0cHM6Ly9pbWdzLXNlYS5hbGlwYXkuY29tL21ndy5odG0iLCJoNWdhdGV3YXkiOiJodHRwczovL29wZW4tc2VhLWdsb2JhbC5hbGlwYXkuY29tL2FwaS9vcGVuL3Jpc2tfY2xpZW50Iiwid29ya1NwYWNlSWQiOiIifSwic2tpcFJlbmRlclBheW1lbnRNZXRob2QiOmZhbHNlfQ%3D%3D",
  "paymentSessionData": "p7uxRxyjzPZv7RaxS8YXirX7n9HxgZLArhnvRvNXiEkIefZbPs72GoLnKObmOWjbW/l86np/SywT9JjZli7MOw==&&US&&188&&eyJlbGlnaWJsZUVhc3lQYXlNYXJrZXRpbmciOmZhbHNlLCJleHRlbmRJbmZvIjoie1wiT1BFTl9NVUxUSV9QQVlNRU5UX0FCSUxJVFlcIjpcImZhbHNlXCIsXCJkaXNwbGF5TGF5b3V0XCI6XCJMRUZUX09SREVSX0FORF9SSUdIVF9QQVlNRU5UXCIsXCJ0aGVtZVR5cGVcIjpcIkxJR0hUXCIsXCJkaXNwbGF5QW50b21Mb2dvXCI6XCJ0cnVlXCJ9IiwibmVlZEFjY291bnRDb25maXJtUGFnZSI6ZmFsc2UsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBTEwiLCJwcm9kdWN0U2NlbmUiOiJDSEVDS09VVF9QQVlNRU5UIiwicHJvZHVjdFNjZW5lVmVyc2lvbiI6IjEuMCJ9LCJzZWN1cml0eUNvbmZpZyI6eyJhcHBJZCI6IiIsImFwcE5hbWUiOiJPbmVBY2NvdW50IiwiYml6VG9rZW4iOiI2VGNkYnIyckYzclBZeDRoa1ZySHFidmoiLCJnYXRld2F5IjoiaHR0cHM6Ly9pbWdzLXNlYS5hbGlwYXkuY29tL21ndy5odG0iLCJoNWdhdGV3YXkiOiJodHRwczovL29wZW4tc2VhLWdsb2JhbC5hbGlwYXkuY29tL2FwaS9vcGVuL3Jpc2tfY2xpZW50Iiwid29ya1NwYWNlSWQiOiIifSwic2tpcFJlbmRlclBheW1lbnRNZXRob2QiOmZhbHNlfQ==",
  "paymentSessionExpiryTime": "2026-01-19T13:45:28+08:00",
  "paymentSessionId": "p7uxRxyjzPZv7RaxS8YXirX7n9HxgZLArhnvRvNXiEnTiY1VosAdwfeqZG715VN+",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
下表展示了响应报文中 result.resultStatus 字段可能返回的值,请您根据指引进行处理:
result.resultStatus
信息
下一步操作
S
表示授权和支付请求已经成功发起。
跳转到 normalUrl 进行下一步。
F
表示授权和支付请求发起失败。
请参考 result.resultCode 和 result.resultMessage 了解错误详情。

步骤 2:跳转到 normalUrl
客户端

商户服务端获取 normalUrl 后,将该 normalUrl 传递给前端,由商户前端跳转至授权和首次支付页面。
Web
if (serverResponse.normalUrl != null) {
  window.open(serverResponse.normalUrl, '_blank');
}
WAP
window.location.href = URL;
iOS
import SafariServices

// 从你的后端接收到 normalUrl 之后
func redirectToSubscription(normalUrl: String) {
    guard let url = URL(string: normalUrl) else { return }

    // 方案 A:使用 SFSafariViewController 打开(推荐,保持在应用内)
    let safariVC = SFSafariViewController(url: url)
    present(safariVC, animated: true)

    // 方案 B:在外部浏览器中打开
    // UIApplication.shared.open(url)
}
Android
import android.content.Intent
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent

// 从你的后端接收到 normalUrl 之后
fun redirectToSubscription(normalUrl: String) {

    // 方案 A:使用 Chrome Custom Tabs 打开(推荐,保持在应用内)
    val customTabsIntent = CustomTabsIntent.Builder().build()
    customTabsIntent.launchUrl(this, Uri.parse(normalUrl))

    // 方案 B:在外部浏览器中打开
    // val intent = Intent(Intent.ACTION_VIEW, Uri.parse(normalUrl))
    // startActivity(intent)
}

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

您可以通过以下方法之一获取授权结果:
  • 接收来自 Antom 的异步通知
  • 主动查询授权结果

接收异步通知

按照以下步骤接收并处理来自 Antom 的异步通知:
  1. 设置接收通知的 webhook URL
买家确认订阅后,Antom 会向您设置的 webhook URL 发送异步通知。您需要存储 subscriptionId 来发起后续的订阅支付。您可以选择以下两种方法之一来设置接收通知的 webhook URL:
  • 若您的每个订单都有单独的通知 URL,建议您在每笔请求中设置 webhook URL。您可以在 createPaymentSession 接口请求的 subscriptionInfo.subscriptionNotifyUrl 参数传入该笔订单的异步通知接收 URL。
  • 若您的所有订单有统一的通知 URL,您可以在 Antom Dashboard > 开发者 > 通知地址 中设置 webhook URL。具体操作请参阅通知地址。
注意:
  • 如果您在接口和 Antom Dashboard 中都指定了此 URL,则接口中配置的 URL 优先级更高。
  • 初始授权完成后,当天无法发起订阅扣款,只能在次日发起。
以下是异步通知请求体的代码示例:
{
  "periodRule": {
    "periodCount": 1,
    "periodType": "WEEK"
  },
  "subscriptionEndTime": "2028-08-08T23:55:16-07:00",
  "subscriptionId": "20260115110000000000000700000014071",
  "subscriptionNotificationType": "CREATE",
  "subscriptionRequestId": "SUBSCRIPTION_20260115194530778_AUTO",
  "subscriptionStartTime": "2026-01-15T04:00:00-08:00",
  "subscriptionStatus": "ACTIVE"
}
  1. 异步通知验签
当您收到 Antom 的异步通知,您需要按照返回收到确认信息的格式返回响应,但无需做加签处理。
您需要按照以下方法对 Antom 发送的支付通知进行验签:
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;
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;

@RestController
public class PaymentNotifyHandleBySDK {

  /**
   * alipay 公钥,用于验证签名
   */
  private static final String SERVER_PUBLIC_KEY = "";

  /**
   * 支付结果通知处理器
   * 使用 <a href="https://spring.io">Spring Framework</a>
   *
   * @param request    HttpServletRequest
   * @param notifyBody 通知体
   * @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"
  }
}

主动查询授权结果

您还可以调用 inquireSubscription 接口主动查询授权结果,使用授权请求中的 subscriptionId 或 subscriptionRequestId查询授权状态。
以下代码展示了如何调用 inquireSubscription 接口:
public static void inquireSubscription() {
  AlipaySubscriptionInquiryRequest request = new AlipaySubscriptionInquiryRequest();
  // 设置你的 subscriptionId
  request.setSubscriptionId(subscriptionId);

  // 查询订阅
  AlipaySubscriptionInquiryResponse response = null;
  try {
    response = CLIENT.execute(request);
  } catch (AlipayApiException e) {
    String errorMsg = e.getMessage();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
使用 subscriptionId
{
  "subscriptionId": "20260119110000000000000910000006774"
}
使用 subscriptionRequestId
{
  "subscriptionRequestId": "SUBSCRIPTION_20260120004816541_AUTO"
}
以下代码展示了一个响应报文的示例:
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "subscription": {
    "currentPeriodEndTime": "2026-07-27T22:42:01+08:00",
    "currentPeriodStartTime": "2026-07-20T22:42:02+08:00",
    "currentPhaseNo": 1,
    "description": "",
    "paymentMethod": {
      "paymentMethodType": "PIX_AUTOMATICO",
      "paymentMethodMetaData": {
        "fixedAmount": {
          "currency": "BRL",
          "value": "200"
        },
        "allowRetry": true,
        "retryMode": "MANUAL"
      }
    },
    "periodCount": 1,
    "periodType": "WEEK",
    "subscriptionId": "202607181000000006700000437470",
    "subscriptionStartTime": "2026-07-20T22:42:02+08:00"
  }
}
下表展示了响应中 result.resultStatus 参数可能返回的值,请您根据指引进行处理:
result.resultStatus
信息
下一步操作
S
表示此接口调用成功并且返回了 normalUrl 。
您可以从 inquireSubscription
接口响应中的 subscriptionStatus 参数获得授权结果。
F
表示此接口调用失败,没有返回 normalUrl。
关于失败原因的更多信息,请参考 result.resultCode。
U
表示接口调用状态未知,请重试。
请使用相同的 subscriptionRequestId 或者 subscriptionId 重试。

步骤 4:获取首次支付结果
服务端

您可以通过以下方法之一获取首次结果:
  • 接收来自 Antom 的异步通知
  • 主动查询首次支付结果

接收异步通知

按照以下步骤接收并处理来自 Antom 的异步通知:
  1. 设置接收通知的 webhook URL
买家确认订阅后,Antom 会向您设置的 webhook URL 发送异步通知。您需要存储 subscriptionId 来发起后续的订阅支付。您可以选择以下两种方法之一来设置接收通知的 webhook URL:
  • 若您的每个订单都有单独的通知 URL,建议您在每笔请求中设置 webhook URL。您可以在createPaymentSession 接口请求的 paymentNotifyUrl 参数传入该笔订单的异步通知接收 URL。
  • 若您的所有订单有统一的通知 URL,您可以在 Antom Dashboard > 开发者 > 通知地址 中设置 webhook URL。具体操作请参阅通知地址。
注意:
  • 如果您在接口和 Antom Dashboard 中都指定了此 URL,则接口中配置的 URL 优先级更高。
  • 初始授权完成后,当天无法发起订阅扣款,只能在次日发起。
以下是异步通知请求体的代码示例:
{
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "BRL",
    "value": "103"
  },
  "paymentCreateTime": "2026-01-15T03:55:02-08:00",
  "paymentId": "20260115114010800100188410251281493",
  "paymentTime": "2026-01-15T03:55:54-08:00",
  "periodEndTime": "2026-02-15T04:30:00-08:00",
  "periodStartTime": "2026-01-15T04:30:00-08:00",
  "phaseNo": "1",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "subscriptionId": "20260115110000000000000700000014073",
  "subscriptionRequestId": "PAYMENT_20260115195444191_AUTO"
}
  1. 异步通知验签
当您收到 Antom 的异步通知,您需要按照返回收到确认信息的格式返回响应,但无需做加签处理。
您需要按照以下方法对 Antom 发送的支付通知进行验签:
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;
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;

@RestController
public class PaymentNotifyHandleBySDK {

  /**
   * alipay 公钥,用于验证签名
   */
  private static final String SERVER_PUBLIC_KEY = "";

  /**
   * 支付结果通知处理器
   * 使用 <a href="https://spring.io">Spring Framework</a>
   *
   * @param request    HttpServletRequest
   * @param notifyBody 通知体
   * @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"
  }
}

主动查询首次支付结果

您还可以调用 inquiryPayment 接口主动查询首次支付结果,使用支付请求中的 paymentId 或 paymentRequestId 查询支付状态。
以下代码展示了如何调用 inquiryPayment 接口:
public static void inquiryPayment() {
  AlipayPaymentInquiryRequest request = new AlipayPaymentInquiryRequest();
  // 设置你的 paymentId 或 paymentRequestId
  request.setPaymentId(paymentId);
  // request.setPaymentRequestId(paymentRequestId);

  // 查询订阅
  AlipayPaymentInquiryResponse response = null;
  try {
    response = CLIENT.execute(request);
  } catch (AlipayApiException e) {
    String errorMsg = e.getMessage();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
使用 paymentId
{
  "paymentId": "20260420114010800100188980200530438"
}
使用 paymentRequestId
{
  "paymentRequestId": "PAYMENT_ede7902a-1dd9-4cae-a151-a758d7442c03"
}
以下代码展示了一个响应报文的示例:
{
    "paymentAmount": {
        "currency": "BRL",
        "value": "101"
    },
    "paymentId": "20260303114010800100188250200530889",
    "paymentMethodType": "PIX_AUTOMATICO",
    "paymentRequestId": "PAYMENT_b0c1265a-033a-4a95-82b8-d7b4875e9c4c",
    "paymentResultCode": "SUCCESS",
    "paymentResultMessage": "success.",
    "paymentStatus": "SUCCESS",
    "paymentTime": "2026-03-03T08:17:45-08:00",
    "retryInfo": {
      "orderId": "20260303110000000000000790000012239",
      "availableRetries": 3,
      "paymentAttempts": {
        "attemptAt": "...",
        "attemptStatus": "EXPIRED"
      }
    }
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}
下表展示了响应中 result.resultStatus 参数可能返回的值,请您根据指引进行处理:
result.resultStatus
信息
下一步操作
S
表示此接口调用成功并且返回了 normalUrl 。
您可以从 inquiryPayment 接口响应中的 paymentStatus 参数获得授权结果。
F
表示此接口调用失败,没有返回 normalUrl。
关于失败原因的更多信息,请参考 result.resultCode。
U
表示接口调用状态未知,请重试。
请使用相同的 paymentRequestId 或者 paymentId 重试。

授权及首次支付后

完成授权和首次支付后,您可以进行以下操作:

发起后续订阅扣款
服务端

买家确认授权后,您需要存储 subscriptionId 以便后续发起订阅扣款。详情请参见发起后续扣款。

终止订阅
服务端

终止订阅功能允许买家在不需要继续使用相关服务时,随时取消当前订阅。详情请参阅取消订阅文档。

取消交易
服务端

对于支付成功后的订单,如买家在当天内申请取消订单或退款,您可以通过 Antom 提供的取消交易能力将订单状态取消或解冻。此外,对于尚未完成支付的订单,您也可以直接进行取消,具体的集成方案见取消交易文档。

退款
服务端

对于已支付成功的订单,如您需向买家发起退款,Antom 提供以下两种方式。
  • 由您的运营人员直接在 Antom Dashboard 平台上进行人工退款。
  • 通过接入 refund 接口发起退款。
Antom 的退款能力如下:
  • 支持全额退款。
  • 支持部分多次退款,多次退款的总金额需小于等于请款金额。
具体的集成方案见退款文档。