Initiate subscription deductions
When the Pix Automático enrollment is completed, you can initial the scheduled payment via pay (Tokenized Payment). Merchant is allowed to the initial the subscription deduction from the customer on any day within the subscription cycle provided the merchant must initial the scheduled payment between 2 and 10 days before the intended deduction date.
Subsequent deduction flow
The subsequent deductions flow is composed of the following steps:
Integration preparations
Before you start integrating, read the Integration Guide and API Overview documents to understand the integration steps of the server-side API and the precautions for calling the API. Furthermore, ensure that the following prerequisites are met:
- Obtain a client ID
- Complete the key configuration
- Complete the configuration of paymentNotifyUrl to receive the asynchronous notification
- Integrate the server-side SDK package, install the server-side library, and initialize a request instance. For more details, refer to Server-side SDKs.
Integration steps
- Initiate the payment request
- Obtain the subsequent deductions result
Step 1: Initiate the payment request Server-side
Call the pay (Tokenized Payment) API to initiate a payment request. The following are key parameters:
Parameter name | Required | Description |
paymentExpiryTime | No | Payment expiration time. After this time, the payment will become invalid, and the acquiring institution or merchant must terminate order processing. Notes:
|
subscriptionInfo.subscriptionId | Yes | The unique ID assigned by Antom to identify a subscription. The value of this parameter is the value of the same parameter that is returned by notifyPayment (Subscription) and notifySubscription for the original subscription. |
subscriptoinInfo.subscriptionOrderId | No | subscriptionOrderId is generated by Antom during the scheduled payments. Note: The parameter is required during the retry payment scenario. |
orderInfo.orderAmount | Yes | The order amount of the merchant that directly provides services or goods to the customer. |
orderInfo.referenceOrderId | Yes | The unique ID to identify the order on the merchant side, which is assigned by the merchant that provides services or goods directly to the customer. |
orderInfo.orderDescription | Yes | Summary description of the order, which is used for user consumption records display or other further actions. |
paymentRequestId | Yes | The unique ID that is assigned by a merchant to identify a payment request. |
paymentAmount.currency | Yes | |
paymentMethod.paymentMethodType | Yes | Set the value of this parameter as PIX_AUTOMATICO. |
productCode | Yes | For scheduled deductions, the value of this parameter is AGREEMENT_PAYMENT. |
public static void schedulePaymentWithPIX() {
AlipayPayRequest request = new AlipayPayRequest();
// replace with your paymentRequestId
request.setPaymentRequestId("PAYMENT_" + UUID.randomUUID());
// set product code for agreement-based payment
request.setProductCode("AGREEMENT_PAYMENT");
// set payment amount
Amount paymentAmount = Amount.builder().currency("BRL").value("100").build();
request.setPaymentAmount(paymentAmount);
// set order info
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);
// set payment method with PIX_AUTOMATICO (scheduled payment)
Map<String, Object> paymentMethodMetaData = new HashMap<>();
PaymentMethod paymentMethod = PaymentMethod.builder()
.paymentMethodType("PIX_AUTOMATICO")
.paymentMethodMetaData(paymentMethodMetaData)
.build();
request.setPaymentMethod(paymentMethod);
// set subscription info (reference existing subscription)
SubscriptionInfo subscriptionInfo = SubscriptionInfo.builder()
.subscriptionDescription("Pix Schedule Payment")
.subscriptionId("20260806190000000000000110000653281")
.build();
request.setSubscriptionInfo(subscriptionInfo);
// set settlement strategy
SettlementStrategy settlementStrategy = SettlementStrategy.builder()
.settlementCurrency("SGD")
.build();
request.setSettlementStrategy(settlementStrategy);
// set payment expiry time
request.setPaymentExpiryTime("2026-01-30T21:00:00-03:00");
// set notification and redirect URLs
request.setPaymentNotifyUrl("https://www.example.com/payments/notifySuccess");
request.setPaymentRedirectUrl("https://www.example.com/redirect");
// execute payment
AlipayPayResponse response = null;
try {
response = CLIENT.execute(request);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// handle error condition
}The following code shows a sample of the request message:
{
"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"
}The following code shows a sample of the response:
{
"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"
}
}The table below shows the possible values of result.resultStatus in the response. Please handle the result according to the guidance provided:
result.resultStatus | Message | Further action |
F | The payment failed. | Refer to the result.resultCode and result.resultMessage for the error details. |
U | Unknown reasons. | When the result.resultCode is PAYMENT_IN_PROCESS, it indicates that the deducation will be completed in the future because it‘s the scheduled payment scenario. For other scenarios, refer to the result.resultCode and result.resultMessage for the details. |
Step 2: Obtain the subsequent deductions result Server-side
You can obtain the subsequent result using one of the following methods:
- Receive asynchronous notifications from Antom
- Inquire about the subsequent deductions result
Receive asynchronous notifications
Follow the steps below to receive and process asynchronous notifications from Antom:
- Configure the webhook URL to receive asynchronous notifications
Once the buyer confirms their subscription, Antom will send a subscription deductions result notification to the webhook URL you set. You can choose one of the following two methods to configure the webhook URL for receiving notifications:
- If each of your orders has a unique notification URL, it is recommended to set the webhook URL in each request. You can pass the asynchronous notification receiving URL for the specific order through paymentNotifyUrl in the pay (Tokenized Payment) API.
- If all your orders share a unified notification URL, you can set the webhook URL on Antom Dashboard through Developer > Notification URL. For detailed steps, refer to Notification URL.
Note: If you specify this URL in both this API and Antom Dashboard, the URL configured in the API takes precedence.
The following code shows a sample of the asynchronous notification request:
{
"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"
}- Verify the asynchronous notification
When you receive an asynchronous notification from Antom, you are required to return the response in the Sample code format, but you do not need to countersign the response.
You need to verify the signature of the enrollment notification sent by 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 public key, used to verify signature
*/
private static final String SERVER_PUBLIC_KEY = "";
/**
* payment result notify processor
* using <a href="https://spring.io">Spring Framework</a>
*
* @param request HttpServletRequest
* @param notifyBody notify body
* @return
*/
@PostMapping("/payNotify")
public Object payNotifyHandler(HttpServletRequest request, @RequestBody String notifyBody) {
// retrieve the required parameters from http request.
String requestUri = request.getRequestURI();
String requestMethod = request.getMethod();
// retrieve the required parameters from request header.
String requestTime = request.getHeader("request-time");
String clientId = request.getHeader("client-id");
String signature = request.getHeader("signature");
Result result;
AlipayResponse response = new AlipayResponse();
try {
// verify the signature of notification
boolean verifyResult = WebhookTool.checkSignature(
requestUri,
requestMethod,
clientId,
requestTime,
signature,
notifyBody,
SERVER_PUBLIC_KEY
);
if (!verifyResult) {
throw new RuntimeException("Invalid notify signature");
}
// deserialize the notification body
// update the order status with notify result
// respond the server that the notification is received
result = new Result("SUCCESS", "success", ResultStatusType.S);
} catch (Exception e) {
String errorMsg = e.getMessage();
// handle error condition
result = new Result("ERROR", errorMsg, ResultStatusType.F);
}
response.setResult(result);
return ResponseEntity.ok().body(response);
}
}Whether the subsequent deductions are successful or not, each notification request must be responded to in the format specified below. Otherwise, Antom will resend the asynchronous notification.
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
}
}Inquire about the payment result
You can also inquire about the authorization result by calling the inquiryPayment API using paymentId or paymentRequestId from the payment request.
public static void inquiryPayment() {
AlipayPaymentInquiryRequest request = new AlipayPaymentInquiryRequest();
// set your paymentId or paymentRequestId
request.setPaymentId(paymentId);
// request.setPaymentRequestId(paymentRequestId);
// Inquiry subscription
AlipayPaymentInquiryResponse response = null;
try {
response = CLIENT.execute(request);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// handle error condition
}
}The following sample code shows a request message:
using paymentId
{
"paymentId": "20260420114010800100188980200530438"
}
using paymentRequestId
{
"paymentRequestId": "PAYMENT_ede7902a-1dd9-4cae-a151-a758d7442c03"
}
The following sample code shows a response message:
{
"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"
}
}(Optional) Step 3: Retry a deduction
When the deduction fails, you can initiate a retry of the deduction yourself.
Merchant initiates a deduction retry
When initiating an authorized subscription, if you have your own scheduling or collection system and need to manually initiate deduction retries after subsequent deduction failures, pass the value MANUAL for the subscriptionInfo.retryMode parameter (in the pay (One-time Payments) API/createPaymentSession (One-time Payments) API) or the retryMode parameter (create API).
Note: The subscriptionOrderId changes after each deduction retry, so you need to obtain the latest subscriptionOrderId for retrying.
The following is a request message for initiating a deduction retry:
{
"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"
}The following is a sample code of the asynchronous notification request body after initiating a deduction retry:
{
"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"
}Common questions
Q: Under what circumstances can merchants initiate a retry for a deduction?
A: Retries can be initiated only when all the following conditions are met:
- The payment result status is failed (result.resultStatus is F).
- Remaining retry attempts are greater than 0 (retryInfo.availableRetries >0).
- Failure reason is "insufficient user balance (result.resultCode is USER_BALANCE_NOT_ENOUGH).
Q: What rules must be followed when initiating a deduction retry?
A: The following rules must be adhered to, otherwise the bank will reject the request:
- Merchants can initiate a retry immediately upon receiving a deduction failure notification, but the bank will execute the deduction on the next day (not the same day).
- A maximum of 3 retries can be attempted within 7 days, with only 1 retry allowed per day.
- Retries are not permitted during the final deduction cycle.
After deductions
After completing the deduction, you can perform the following actions:
Cancel Server-side
For orders that have been successfully paid, if the buyer requests to cancel the order or refund on the same day, you can use Antom's cancel transaction capability to cancel or unfreeze the order status. Additionally, for orders that have not yet completed payment, you can also directly cancel them. For detailed integration solutions, please refer to Cancel.
Refund Server-side
For orders that have been successfully paid, if you need to initiate a refund to the buyer, Antom offers the following two methods:
- Your operation staff can manually process the refund directly on the Antom Dashboard.
- You can initiate a refund by integrating with the refund API.
Antom's refund capabilities include:
- Support for full refunds.
- Support for partial multiple refunds, with the total amount of multiple refunds not exceeding the captured amount.