Antom, leading provider of tailored payment solutions

发起后续扣款

在 Pix Automático 授权完成后,您可以通过 pay(令牌支付)接口来发起后续扣款。您只能在到期日前 2-10 个日历日内(即在账单周期开始日前)发起后续扣款。

后续扣款流程

后续流程分为以下步骤:

集成准备

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

集成步骤

  1. 发起支付请求
  2. 获取后续扣款结果

步骤 1:发起支付请求
服务端

调用 pay(令牌支付)接口来发起支付请求。以下是重点参数:
参数名
是否必需
描述
paymentExpiryTime
否
支付过期时间,超过这个时间后,支付将失效,收单机构或商户必须终止订单处理。
注意:
  • 在预定付款场景中,此参数是必需的,表示到期日。
  • 在重试付款场景中,此参数不是必需的。
subscriptionInfo.subscriptionId
是
由 Antom 分配的唯一ID,用于识别订阅。此参数的值与 notifyPayment(订阅) 和 notifySubscription 为原始订阅返回的相同参数的值相同。
subscriptoinInfo.subscriptionOrderId
否
当前订阅订单 ID。 ​
注意:此参数在重试场景下必传。
orderInfo.orderAmount
是
直接向客户提供服务或商品的商户的订单金额。此字段用于用户消费记录显示或支付结果页面。
orderInfo.referenceOrderId
是
在商户端识别订单的专属 ID,由直接向客户提供服务或商品的商户分配。
orderInfo.orderDescription
是
订单的摘要描述,用于用户消费记录显示或其他进一步操作。
paymentRequestId
是
商户为识别支付请求而分配的专属 ID。
paymentAmount.currency
是
交易金额币种。币种代码,值为遵循 ISO 4217 标准的三位币种代码。
paymentMethod.paymentMethodType
是
设置此参数的值为 PIX_AUTOMATICO。
productCode
是
对于周期扣款场景,此参数值为 AGREEMENT_PAYMENT。
完整参数和额外要求请参考 pay(令牌支付)接口。
以下示例代码展示了如何调用 pay(令牌支付)接口:
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 的异步通知:
  1. 设置接收通知的 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"
}
  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"
    }
}

(可选)步骤 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 的退款能力如下:
  • 支持全额退款。
  • 支持部分多次退款,多次退款的总金额需小于等于请款金额。
具体的集成方案见退款文档。