发起后续扣款
后续扣款流程
后续流程分为以下步骤:
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
集成步骤
- 发起支付请求
- 获取后续扣款结果
步骤 1:发起支付请求 服务端
参数名 | 是否必需 | 描述 |
paymentExpiryTime | 否 | 支付过期时间,超过这个时间后,支付将失效,收单机构或商户必须终止订单处理。 注意:
|
subscriptionInfo.subscriptionId | 是 | |
subscriptoinInfo.subscriptionOrderId | 否 | 当前订阅订单 ID。 注意:此参数在重试场景下必传。 |
orderInfo.orderAmount | 是 | 直接向客户提供服务或商品的商户的订单金额。此字段用于用户消费记录显示或支付结果页面。 |
orderInfo.referenceOrderId | 是 | 在商户端识别订单的专属 ID,由直接向客户提供服务或商品的商户分配。 |
orderInfo.orderDescription | 是 | 订单的摘要描述,用于用户消费记录显示或其他进一步操作。 |
paymentRequestId | 是 | 商户为识别支付请求而分配的专属 ID。 |
paymentAmount.currency | 是 | |
paymentMethod.paymentMethodType | 是 | 设置此参数的值为 PIX_AUTOMATICO。 |
productCode | 是 | 对于周期扣款场景,此参数值为 AGREEMENT_PAYMENT。 |
public static void schedulePaymentWithPIX() {
AlipayPayRequest request = new AlipayPayRequest();
// 替换为你的 paymentRequestId
request.setPaymentRequestId("PAYMENT_" + UUID.randomUUID());
// 设置基于协议支付的 product code
request.setProductCode("AGREEMENT_PAYMENT");
// 设置支付金额
Amount paymentAmount = Amount.builder().currency("BRL").value("100").build();
request.setPaymentAmount(paymentAmount);
// 设置订单信息
Amount orderAmount = Amount.builder().currency("BRL").value("100").build();
Merchant merchant = Merchant.builder()
.referenceMerchantId(new Random().nextInt(100000))
.build();
Order order = Order.builder()
.orderAmount(orderAmount)
.orderDescription("Pix Schedule Payment")
.referenceOrderId("ORDER_" + UUID.randomUUID())
.merchant(merchant)
.build();
request.setOrder(order);
// 使用 PIX_AUTOMATICO 设置支付方式(预约支付)
Map<String, Object> paymentMethodMetaData = new HashMap<>();
PaymentMethod paymentMethod = PaymentMethod.builder()
.paymentMethodType("PIX_AUTOMATICO")
.paymentMethodMetaData(paymentMethodMetaData)
.build();
request.setPaymentMethod(paymentMethod);
// 设置订阅信息(引用现有订阅)
SubscriptionInfo subscriptionInfo = SubscriptionInfo.builder()
.subscriptionDescription("Pix Schedule Payment")
.subscriptionId("20260806190000000000000110000653281")
.build();
request.setSubscriptionInfo(subscriptionInfo);
// 设置 settlement strategy
SettlementStrategy settlementStrategy = SettlementStrategy.builder()
.settlementCurrency("SGD")
.build();
request.setSettlementStrategy(settlementStrategy);
// 设置支付过期时间
request.setPaymentExpiryTime("2026-01-30T21:00:00-03:00");
// 设置通知和重定向 URL
request.setPaymentNotifyUrl("https://www.example.com/payments/notifySuccess");
request.setPaymentRedirectUrl("https://www.example.com/redirect");
// 执行支付
AlipayPayResponse response = null;
try {
response = CLIENT.execute(request);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// 处理错误情况
}以下代码展示了一个请求报文的示例:
{
"order": {
"orderAmount": {
"currency": "BRL",
"value": "100"
},
"orderDescription": "Pix Schedule Payment",
"referenceOrderId": "876543234567"
},
"paymentAmount": {
"currency": "BRL",
"value": "100"
},
"paymentMethod": {
"paymentMethodType": "PIX_AUTOMATICO"
},
"subscriptionInfo": {
"subscriptionDescription": "Pix Schedule Payment",
"subscriptionId": "..."
},
"settlementStrategy": {
"settlementCurrency": "USD"
},
"paymentExpiryTime": "2026-01-07T21:00:00-03:00", //send local timezone
"paymentNotifyUrl": "https://pix.alipay.cn/payments/notifySuccess",
"paymentRequestId": "PAYMENT_1234567890001",
"productCode": "AGREEMENT_PAYMENT"
}以下代码展示了一个响应的示例:
{
"paymentAmount": {
"currency": "BRL",
"value": "1100"
},
"paymentCreateTime": "2020-07-03T01:17:50-07:00",
"paymentId": "2020070311401080010018840027964XXXX",
"paymentRequestId": "AGREEMENT_PAYMENT_REQUEST_2020070316170XXXX",
"result": {
"resultCode": "PAYMENT_IN_PROCESS",
"resultMessage": "payment in process",
"resultStatus": "U"
}
}下表展示了响应报文中 result.resultStatus 字段可能返回的值,请您根据指引进行处理:
result.resultStatus | 信息 | 下一步操作 |
F | 支付失败。 | 查看 result.resultCode 和 result.resultMessage 了解详细失败原因。 |
U | 未知原因。 | 当 result.resultCode 为 PAYMENT_IN_PROCESS 时,表示扣款将在未来完成,因为这是预定付款场景。对于其他场景,请参考 result.resultCode 和 result.resultMessage 获取详细信息。 |
步骤 2:获取后续扣款结果 服务端
您可以通过以下方法之一获取后续扣款结果:
- 接收来自 Antom 的异步通知
- 主动查询后续扣款结果
接收异步通知
按照以下步骤接收并处理来自 Antom 的异步通知:
- 设置接收通知的 webhook URL
买家确认订阅后,Antom 会向您设置的 webhook URL 发送异步通知。您需要存储 subscriptionId 来发起后续的订阅支付。您可以选择以下两种方法之一来设置接收通知的 webhook URL:
- 若您的每个订单都有单独的通知 URL,建议您在每笔请求中设置 webhook URL。您可以在 pay(令牌支付)接口请求的 paymentNotifyUrl 参数传入该笔订单的异步通知接收 URL。
- 若您的所有订单有统一的通知 URL,您可以在 Antom Dashboard > 开发者 > 通知地址 中设置 webhook URL。具体操作请参阅通知地址。
注意:如果您在接口和 Antom Dashboard 中都指定了此 URL,则接口中配置的 URL 优先级更高。
以下是异步通知请求体的代码示例:
{
"notifyType": "PAYMENT_RESULT",
"subscriptionOrderId": "20260303110000000000000700000018843",
"paymentAmount": {
"currency": "BRL",
"value": "100"
},
"paymentCreateTime": "2025-06-24T03:00:20-07:00",
"paymentId": "20250826154010891000188200294996568",
"paymentTime": "2025-06-24T03:00:20-07:00",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultStatus": "S"
},
"retryInfo": {
"availableRetries": 0,
"paymentAttempts": [
{
"attemptAt": "2025-08-28T00:53:11+00:00",
"attemptResponse": "PAID"
}
]
},
"subscriptionId": "20250827110000000000000970000003421",
"subscriptionRequestId": "20990501211250825864494864277"
}- 异步通知验签
您需要按照以下方法对 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"
}
}主动查询首次支付结果
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"
}
}(可选)步骤 3:发起扣款重试
当扣款失败时,您可以自行发起扣款重试。
商户发起扣款重试
在发起授权订阅时,如果您有自己的调度或催收系统,需要在后续扣款失败后自行发起扣款重试,请传入 subscriptionInfo.retryMode 字段(pay (单笔支付)/createPaymentSession(单笔支付)接口)或 retryMode 字段(create 接口)的值为 MANUAL。
注意:subscriptionOrderId 在每次扣款重试后都会发生变化,需要获取最新的 subscriptionOrderId 用于重试。
以下是一个发起扣款重试的请求报文示例:
{
"order": {
"orderAmount": {
"currency": "BRL",
"value": "100"
},
"orderDescription": "Cappuccino #grande (Mika's coffee shop)",
"referenceOrderId":"876543234567"
},
"paymentAmount": {
"currency": "BRL",
"value": "100"
},
"paymentMethod": {
"paymentMethodType": "PIX_AUTOMATICO"
},
"subscriptionInfo": {
"subscriptionDescription": "Joyland Standard Annual Membership",
"subscriptionId": "..."
"subscriptionOrderId": "111111111"
},
"settlementStrategy": {
"settlementCurrency": "SGD"
},
"paymentNotifyUrl": "https://kademo.intlalipay.cn/payments/notifySuccess",
"paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
"paymentRequestId": "PAYMENT_123456789000111",
"productCode": "AGREEMENT_PAYMENT"
}以下是发起扣款重试后,异步通知请求体的代码示例:
{
"notifyType": "PAYMENT_PENDING",
"subscriptionOrderId": "2222222222",
"paymentAmount": {
"currency": "KRW",
"value": "76836"
},
"paymentCreateTime": "2025-06-24T03:00:20-07:00",
"paymentId": "20250826154010891000188200294996568",
"paymentTime": "2025-06-24T03:00:20-07:00",
"result": {
"resultCode": "USER_BALANCE_NOT_ENOUGH",
"resultMessage": "The user's balance is insufficient for the payment.",
"resultStatus": "F"
},
"retryInfo": {
"availableRetries": 2,
"paymentAttempts": [
{
"attemptAt": "2025-08-27 00:53:11",
"attemptResponse": "Insufficient funds or limit restrictions in the user's account"
}
]
},
"subscriptionId": "20250827110000000000000970000003421",
"subscriptionRequestId": "20990501211250825864494864277"
}
常见问题
问:商户什么情况下可以对扣款发起重试?
答:同时满足以下所以条件时方可重试:
- 支付结果状态为失败(result.resultStatus 为 F)。
- 剩余可重试次数大于零(retryInfo.availableRetries >0)。
- 失败原因为“用户余额不足”(result.resultCode 为 USER_BALANCE_NOT_ENOUGH)。
问:发起扣款重试需要遵循哪些规则?
答:必须遵守以下规则,否则银行将拒绝请求:
- 商家收到扣款失败通知后可立即发起重试,但银行将在次日(而非当天)执行扣款。
- 在 7 天内最多可重试 3 次,且每天仅能发起 1 次重试。
- 不允许在扣款的最后周期进行重试。
扣款后
后续扣款后,您可以进行以下操作:
取消交易 服务端
对于支付成功后的订单,如买家在当天内申请取消订单或退款,您可以通过 Antom 提供的取消交易能力将订单状态取消或解冻。此外,对于尚未完成支付的订单,您也可以直接进行取消,具体的集成方案见取消交易文档。
退款 服务端
对于已支付成功的订单,如您需向买家发起退款,Antom 提供以下两种方式。
- 由您的运营人员直接在 Antom Dashboard 平台上进行人工退款。
- 通过接入 refund 接口发起退款。
Antom 的退款能力如下:
- 支持全额退款。
- 支持部分多次退款,多次退款的总金额需小于等于请款金额。