Antom, leading provider of tailored payment solutions

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

  1. Initiate the payment request
  2. 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:
  • In the scheduled payment scenario, this parameter is required and represents the due date.
  • In the retry payment scenario, this parameter is not required.
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
The transaction currency, which is a 3-letter currency code that follows the ISO 4217 standard.
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.
For full parameters and additional requirements, refer to the pay (Tokenized Payment) API.
The following sample code shows how to call the pay (Tokenized Payment) API:
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:
  1. 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"
}
  1. 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.
The following sample code shows how to call the inquiryPayment API:
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.
For detailed integration solutions, please refer to Refund.