仅授权
本文描述如何集成 Pix Automático 授权。
授权流程
授权流程分为以下步骤:
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
集成步骤
- 发起授权请求
- 跳转到授权页面(normalUrl)
- 获取授权结果
步骤 1:发起授权请求 服务端
参数名 | 是否必需 | 描述 |
allowRetry | 否 | 表示当定期扣款因余额不足而失败时是否允许您发起重试。有效值为:
|
retryMode | 否 | 重试模式。有效值为:
|
paymentMethod.paymentMethodMetaData.maxAmountFloor | 否 | 该值表示商家在后续周期扣款中可向用户收取金额的最低值。 注意:
|
paymentMethodMetaData.fixedAmount.currency | 否 | |
paymentMethodMetaData.fixedAmount.value | 否 | 固定订阅金额币种。 |
paymentMethod.paymentMethodMetaData.cpf | 否 | 用户的巴西个人税号。此参数仅适用于 Pix Automático 支付方式。如果未传递此参数,将打开 Pix Automático 应用程序的中间页面以收集数据完成支付。如果已传递此参数,数据将显示在中间页面上。 |
paymentMethod.paymentMethodMetaData.fullName | 否 | 买家的全名。如果未传递此参数,将打开 Pix Automático 应用程序的中间页面以收集数据完成支付。如果已传递此参数,数据将显示在中间页面上。 |
periodRule.periodType | 是 | 此参数仅用于 Pix Automático 定期扣款场景。 有效值为:
|
periodRule.periodCount | 是 | 一个订阅周期内周期类型的数量。请将该参数的值设置为 1。 注意:当前仅支持取值为 1,暂不支持 2、3 等其他取值。 |
subscriptionRequestId | 是 | 商户为识别订阅请求分配的专属 ID。Antom 使用此参数进行幂等性控制。 |
subscriptionDescription | 是 | 订阅的描述,用于显示用户消费记录及进行其他操作。 |
subscriptionRedirectUrl | 是 | 用户授权订阅后跳转到的商户页面链接。 |
subscriptionStartTime | 是 | 订阅首笔付款的扣款日期和时间。 注意:
|
paymentMethod.paymentMethodType | 是 | 设置此参数的值为 PIX_AUTOMATICO。 |
subscriptionNotificationUrl | 是 | 用于接收订阅结果通知的地址。 |
paymentNotificationUrl | 否 | 用于接收每个订阅周期支付结果通知的地址。 |
orderInfo.orderAmount | 否 | 折扣或税费应用前的订单总额。此参数的值会显示在用户消费记录或支付结果页面上。 |
paymentAmount | 是 | 每个订阅周期向用户收取的支付金额。 注意:
|
settlementStrategy.settlementCurrency | 是 | 商户希望结算的币种的 ISO 币种代码。如果商户注册了多种币种结算,此参数是必需的。 |
env.terminalType | 是 | 指定买家发起交易的端类型:
|
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 的异步通知:
- 设置接收通知的 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"
}- 异步通知验签
您需要按照以下方法对 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"
}
}主动查询授权结果
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 。 | |
F | 表示此接口调用失败,没有返回 normalUrl。 | 关于失败原因的更多信息,请参考 result.resultCode。 |
U | 表示接口调用状态未知,请重试。 | 请使用相同的 subscriptionRequestId 或者 subscriptionId 重试。 |
授权后
完成授权后,您可以进行以下操作: