Antom, leading provider of tailored payment solutions

仅授权

本文描述如何集成 Pix Automático 授权。

授权流程

授权流程分为以下步骤:

集成准备

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

集成步骤

  1. 发起授权请求
  2. 跳转到授权页面(normalUrl)
  3. 获取授权结果

步骤 1:发起授权请求
服务端

调用 create 接口来发起授权请求。以下是发起授权请求参数的重点参数:
参数名
是否必需
描述
allowRetry
否
表示当定期扣款因余额不足而失败时是否允许您发起重试。有效值为:
  • true:表示当定期扣款因余额不足而失败时允许您发起重试。
  • false:默认值。表示当定期扣款因余额不足而失败时不允许您发起重试。
retryMode
否
重试模式。有效值为:
  • MANUAL:默认值。如果您有自己的调度或催收系统,请选择此值。详情请参考商户发起扣款重试。
paymentMethod.paymentMethodMetaData.maxAmountFloor
否
该值表示商家在后续周期扣款中可向用户收取金额的最低值。
注意:
  • 用户可在 app 设置中设定该授权的最高扣款金额,但不得低于商户设定的 maxAmountFloor。示例:如果商家设置为 100 BRL,而用户在 app 中将最高抵扣金额设为 200 BRL,则商家在后续扣款时只能扣除 100 至 200 BRL 之间的金额。
  • 此参数仅用于 Pix Automático 定期扣款场景。
paymentMethodMetaData.fixedAmount.currency
否
固定订阅金额币种。币种代码,值为遵循 ISO 4217 标准的三位币种代码。
paymentMethodMetaData.fixedAmount.value
否
固定订阅金额币种。
paymentMethod.paymentMethodMetaData.cpf
否
用户的巴西个人税号。此参数仅适用于 Pix Automático 支付方式。如果未传递此参数,将打开 Pix Automático 应用程序的中间页面以收集数据完成支付。如果已传递此参数,数据将显示在中间页面上。
paymentMethod.paymentMethodMetaData.fullName
否
买家的全名。如果未传递此参数,将打开 Pix Automático 应用程序的中间页面以收集数据完成支付。如果已传递此参数,数据将显示在中间页面上。
periodRule.periodType
是
此参数仅用于 Pix Automático 定期扣款场景。 有效值为:
  • WEEK:表示订阅周期以周为单位。
  • MONTH:表示订阅周期以月为单位。
  • QUARTER:表示订阅周期以季为单位。
  • HALF_YEAR:表示订阅周期以半年为单位。
  • YEAR:表示订阅周期以年为单位。
periodRule.periodCount
是
一个订阅周期内周期类型的数量。请将该参数的值设置为 1。​
注意:当前仅支持取值为 1,暂不支持 2、3 等其他取值。
subscriptionRequestId ​
是
商户为识别订阅请求分配的专属 ID。Antom 使用此参数进行幂等性控制。
subscriptionDescription
是
订阅的描述,用于显示用户消费记录及进行其他操作。
subscriptionRedirectUrl
是
用户授权订阅后跳转到的商户页面链接。
subscriptionStartTime
是
订阅首笔付款的扣款日期和时间。​
注意:
  • 当首期扣费免费时,设定该参数的值为下一次扣款日。
  • 订阅生效时间至少为未来 48 小时。
paymentMethod.paymentMethodType
是
设置此参数的值为 PIX_AUTOMATICO。
subscriptionNotificationUrl
是
用于接收订阅结果通知的地址。
paymentNotificationUrl
否
用于接收每个订阅周期支付结果通知的地址。
orderInfo.orderAmount
否
折扣或税费应用前的订单总额。此参数的值会显示在用户消费记录或支付结果页面上。
paymentAmount
是
每个订阅周期向用户收取的支付金额。 ​
注意:
  • 仅当您的订阅周期扣费都是固定值时需要传入此参数。
  • 当周期扣款中有可变金额时,不要传入此参数。例如:首期扣款免费或者打折。
settlementStrategy.settlementCurrency
是
商户希望结算的币种的 ISO 币种代码。如果商户注册了多种币种结算,此参数是必需的。
env.terminalType
是
指定买家发起交易的端类型:
  • WEB:客户端终端类型为网站,通过 PC 浏览器打开。
  • WAP:客户端终端类型为 H5 页面,通过移动浏览器打开。
  • APP:客户端终端类型为移动应用。
完整参数和额外要求请参考 create 接口。
以下示例代码展示了如何调用 create 接口:
public static void createSubscriptionWithPIX() {
  AlipaySubscriptionCreateRequest request = new AlipaySubscriptionCreateRequest();

  // 替换为你的 subscriptionRequestId
  String subscriptionRequestId = "SUBSCRIPTION_20260115181300008_AUTO";
  request.setSubscriptionRequestId(subscriptionRequestId);

  // 设置订阅描述
  request.setSubscriptionDescription("Monthly Premium Membership");

  // 设置 paymentMethod
  PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("PIX_AUTOMATICO").build();

  // 设置 Pix Automático 相关参数
  Map<String, Object> paymentMethodMetaData = new HashMap<>();
  paymentMethodMetaData.put("cpf", "02859464980");
  paymentMethodMetaData.put("fullName", "full name");
  paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);

  // 在 payment method 上设置固定金额
  Amount fixedAmount = Amount.builder().currency("BRL").value("1100").build();
  paymentMethod.setFixedAmount(fixedAmount);

  request.setPaymentMethod(paymentMethod);

  // 设置 env info
  Env env = Env.builder().osType(OsType.ANDROID).terminalType(TerminalType.WAP).build();
  request.setEnv(env);

  // 设置 order info
  Amount orderAmount = Amount.builder().currency("BRL").value("1100").build();
  OrderInfo orderInfo = OrderInfo.builder().orderAmount(orderAmount).build();
  request.setOrderInfo(orderInfo);

  // 设置重试配置
  request.setAllowRetry(true);
  request.setRetryMode("MANUAL");

  // 设置 period rule
  PeriodRule periodRule = PeriodRule.builder().periodType("MONTH").periodCount(1).build();
  request.setPeriodRule(periodRule);

  // 设置 settlement strategy
  SettlementStrategy settlementStrategy = SettlementStrategy.builder()
    .settlementCurrency("BRL")
    .build();
  request.setSettlementStrategy(settlementStrategy);

  // 设置订阅开始和结束时间
  request.setSubscriptionStartTime("YYYY-MM-ddThh:mm:ss+xx:xx");
  request.setSubscriptionEndTime("YYYY-MM-ddThh:mm:ss+xx:xx");

  // 替换为你的通知 URL
  request.setSubscriptionNotificationUrl("https://merchant.com/sub-notify");
  request.setPaymentNotificationUrl("https://merchant.com/pay-notify");

  // 替换为你的重定向 URL
  request.setSubscriptionRedirectUrl("https://merchant.com/redirect");

  // 创建订阅
  AlipaySubscriptionCreateResponse response = null;
  try {
    response = CLIENT.execute(request);
  } catch (AlipayApiException e) {
    String errorMsg = e.getMessage();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
{
  "subscriptionRequestId": "SUBSCRIPTION_20260115181300008_AUTO",
  "subscriptionDescription": "Monthly Premium Membership",
  "paymentMethod": {
    "paymentMethodType": "PIX_AUTOMATICO",
    "paymentMethodMetaData": {
      "cpf": "02859464980",
      "fullName": "full name"
    },
    "fixedAmount": {
      "currency": "BRL",
      "value": "1100"
    }
  },
  "env": {
    "osType": "ANDROID",
    "terminalType": "WAP"
  },
  "orderInfo": {
    "orderAmount": {
      "currency": "BRL",
      "value": "1100"
    }
  },
  "allowRetry": true,
  "retryMode": "MANUAL",
  "periodRule": {
    "periodType": "MONTH",
    "periodCount": 1
  },
  "settlementStrategy": {
    "settlementCurrency": "BRL"
  },
  "subscriptionStartTime": "YYYY-MM-ddThh:mm:ss+xx:xx",
  "subscriptionEndTime": "YYYY-MM-ddThh:mm:ss+xx:xx",
  "subscriptionNotificationUrl": "https://merchant.com/sub-notify",
  "paymentNotificationUrl": "https://merchant.com/pay-notify",
  "subscriptionRedirectUrl": "https://merchant.com/redirect"
}
以下代码展示了一个响应的示例:
{
  "normalUrl": "https://checkout.antom.com/checkout-page/pages/subscriptions/index.html?sessionData=o93pxYXaCCAlcHAZNiPJhqOINrfJIoVm2SoK4JuyzAkrsi0sPrz5wULwI1gnbYtPUn%2FWNojZoBJeGzyj1yKoJw%3D%3D%26%26US%26%26188%26%26...",
  "orderCodeForm": {
    "codeDetails": [
      {
        "codeValue": "00020126180014br.gov.bcb.pix5204000053039865802BR5908AlipayBR6009Sao Paulo61080400404062070503***80950014br.gov.bcb.pix2573api.developer.btgpactual.com/pc/p/v2/rec/842a463c70424c88830515bf7e6bf94e6304CE52",
        "codeValueType": "DIGICODE",
        "displayType": "TEXT"
      },
      {
        "codeValue": "00020126180014br.gov.bcb.pix5204000053039865802BR5908AlipayBR6009Sao Paulo61080400404062070503***80950014br.gov.bcb.pix2573api.developer.btgpactual.com/pc/p/v2/rec/842a463c70424c88830515bf7e6bf94e6304CE52",
        "codeValueType": "QRCODE",
        "displayType": "IMAGE"
      }
    ],
    "expireTime": "1785141048615",
    "paymentMethodType": "PIX_AUTOMATICO"
  },
  "paymentSessionData": "o93pxYXaCCAlcHAZNiPJhqOINrfJIoVm2SoK4JuyzAkrsi0sPrz5wULwI1gnbYtPUn/WNojZoBJeGzyj1yKoJw==&&US&&188&&...",
  "paymentSessionExpiryTime": "2026-07-27T17:16:48+08:00",
  "paymentSessionId": "o93pxYXaCCAlcHAZNiPJhqOINrfJIoVm2SoK4JuyzAlLA2qulE35pfcnFgFcCVD4",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
下表展示了响应报文中 result.resultStatus 字段可能返回的值,请您根据指引进行处理:
result.resultStatus
信息
下一步操作
S
表示授权请求已经成功发起。
跳转到 normalUrl 进行下一步。
U
表示由于未知原因,创建授权请求失败。
请重新调用 API 以解决该问题。如问题仍然存在,请联系 Antom 技术支持。
F
表示授权请求发起失败。
请参考 result.resultCode 和 result.resultMessage 获取错误详情。
注意:如果未收到响应消息,可能是由于网络超时导致。请更换 paymentRequestId 后重新调用 API,以解决该问题。

步骤 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。您可以在 create 接口请求的 subscriptionNotificationUrl 参数传入该笔订单的异步通知接收 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 {

  /**
   * 支付宝公钥,用于验证签名
   */
  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 重试。

授权后

完成授权后,您可以进行以下操作:

发起后续订阅扣款
服务端

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

终止订阅
Server-side

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