Antom, leading provider of tailored payment solutions

Enrollment-only

This topic describes how to integrate Pix Automático enrollment.

Enrollment flow

The enrollment 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 an enrollment request
  2. Redirect to the enrollment page (normalUrl)
  3. Obtain the enrollment result

Step 1: Initiate an enrollment request
Server-side

Call the create API to initiate an enrollment request. The following are key parameters for initiating an enrollmentrequest:
Parameter name
Required
Description
allowRetry
No
Indicates whether you are allowed to initiate a retry when a recurring payment fails due to insufficient balance. Valid values are:
  • true: Indicates that you are allowed to initiate a retry when a recurring payment fails due to insufficient balance.
  • false: The default value, indicates that you are not allowed to initiate a retry when a recurring payment fails due to insufficient balance.
retryMode
No
The retry mode. Valid value is:
paymentMethod.paymentMethodMetaData.maxAmountFloor
No
This value represents the minimum amount merchants can deduct from users for recurring payments. ​
Notes:
  • Users can set the maximum deduction amount for this authorization in the app settings, but it cannot be lower than the maxAmountFloor set by the merchant. For example, if the merchant sets 100 BRL and the user sets the maximum deductible amount to 200 BRL in the app, then the merchant can only deduct amounts between 100 BRL and 200 BRL in subsequent charges.
  • This parameter is only used in Pix Automático recurrence scenarios.
paymentMethodMetaData.fixedAmount.currency
No
The currency of the fixed subscription amount. The transaction currency, which is a 3-letter currency code that follows the ISO 4217 standard.
paymentMethodMetaData.fixedAmount.value
No
The value of the fixed subscription amount.
paymentMethod.paymentMethodMetaData.cpf
No
User's Brazilian individual tax ID. This parameter is only for Pix Automático payment method. If it is not passed, it will open the Pix Automático application's middle page to collect the data to complete the payment. If it is passed, the data will be displayed on the middle page.
paymentMethod.paymentMethodMetaData.fullName
No
The full name of the buyer. If it is not passed, it will open the Pix Automático application's middle page to collect the data to complete the payment. If it is passed, the data will be displayed on the middle page.
periodRule.periodType
Yes
The frequency at which the buyer will be charged. Valid values are:
  • WEEK: The subscription is billed on a weekly basis.
  • MONTH: The subscription is billed on a monthly basis.
  • QUARTER: The subscription is billed on a quarterly basis (every 3 months).
  • HALF_YEAR: The subscription is billed on a semi-annual basis (every 6 months).
  • YEAR: The subscription is billed on an annual basis.
periodRule.periodCount
Yes
The number of period types within one subscription period. Please set the value to 1.​
Note: Currently, only the value 1 is supported; values such as 2 and 3 are not supported.
subscriptionRequestId ​
Yes
The unique ID assigned by a merchant to identify a subscription request. Antom uses this field for idempotency control.
subscriptionDescription
Yes
The description of the subscription, used for displaying user consumption records and other actions.
subscriptionRedirectUrl
Yes
The merchant page URL that the user is redirected to after authorizing the subscription.
subscriptionStartTime
Yes
The date and time when the initial subscription payment is charged.
Notes:
  • When the first deduction is free, set this parameter to the date of the next deduction.
  • The start time has to be at least 48 hours in the future.
paymentMethod.paymentMethodType
Yes
Set the value of this parameter as PIX_AUTOMATICO.
subscriptionNotificationUrl
Yes
The URL that is used to receive the subscription result notification.
paymentNotificationUrl
No
The URL that is used to receive the payment result notification for each subscription period.
orderInfo.orderAmount
No
The total amount of the order before discounts or taxes are applied. The value of this parameter is displayed on user consumption records or the payment result page.
paymentAmount
No
The payment amount charged to the user per subscription period. ​
Notes:
  • Only pass this parameter when your subscription cycle is with a fixed amount.
  • When the subcription cycle is with a variable amount, do no pass this parameter. For example, the first deduction is free or has discount,
settlementStrategy.settlementCurrency
Yes
The ISO currency code of the currency that the merchant wants to be settled against. The parameter is required if the merchant signed up for multiple currencies to settle.
env.terminalType
Yes
The terminal type the merchant service applies to. Valid values are:
  • WEB: The client-side terminal type is a website, which is opened via a PC browser.
  • WAP: The client-side terminal type is an H5 page, which is opened via a mobile browser.
  • APP: The client-side terminal type is a mobile application.
For full parameters and additional requirements, refer to the create API.
The following sample code shows how to call the create API:
public static void createSubscriptionWithPIX() {
  AlipaySubscriptionCreateRequest request = new AlipaySubscriptionCreateRequest();

  // replace with your subscriptionRequestId
  String subscriptionRequestId = "SUBSCRIPTION_20260115181300008_AUTO";
  request.setSubscriptionRequestId(subscriptionRequestId);

  // set subscription description
  request.setSubscriptionDescription("Monthly Premium Membership");

  // set paymentMethod
  PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("PIX_AUTOMATICO").build();

  // set Pix Automático related parameters
  Map<String, Object> paymentMethodMetaData = new HashMap<>();
  paymentMethodMetaData.put("cpf", "02859464980");
  paymentMethodMetaData.put("fullName", "full name");
  paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);

  // set fixed amount on payment method
  Amount fixedAmount = Amount.builder().currency("BRL").value("1100").build();
  paymentMethod.setFixedAmount(fixedAmount);

  request.setPaymentMethod(paymentMethod);

  // set env info
  Env env = Env.builder().osType(OsType.ANDROID).terminalType(TerminalType.WAP).build();
  request.setEnv(env);

  // set order info
  Amount orderAmount = Amount.builder().currency("BRL").value("1100").build();
  OrderInfo orderInfo = OrderInfo.builder().orderAmount(orderAmount).build();
  request.setOrderInfo(orderInfo);

  // set retry configuration
  request.setAllowRetry(true);
  request.setRetryMode("MANUAL");

  // set period rule
  PeriodRule periodRule = PeriodRule.builder().periodType("MONTH").periodCount(1).build();
  request.setPeriodRule(periodRule);

  // set settlement strategy
  SettlementStrategy settlementStrategy = SettlementStrategy.builder()
    .settlementCurrency("BRL")
    .build();
  request.setSettlementStrategy(settlementStrategy);

  // set subscription start and end time
  request.setSubscriptionStartTime("YYYY-MM-ddThh:mm:ss+xx:xx");
  request.setSubscriptionEndTime("YYYY-MM-ddThh:mm:ss+xx:xx");

  // replace with your notification urls
  request.setSubscriptionNotificationUrl("https://merchant.com/sub-notify");
  request.setPaymentNotificationUrl("https://merchant.com/pay-notify");

  // replace with your redirect url
  request.setSubscriptionRedirectUrl("https://merchant.com/redirect");

  // create subscription
  AlipaySubscriptionCreateResponse 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:
{
  "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"
}
The following code shows a sample of the response:
{
  "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
Message
Further action
S
Indicates that enrolment request is initiated successfully
Redirect to normalUrl to proceed the next step.
U
Indicates that enrolment request creation failed for unknown reasons.
Please call the API again to resolve the issue. Please contact Antom technical support if the problem persists.
F
Indicates that the enrolment request failed to be initiated
Refer to the result.resultCode and result.resultMessage for the error details.

Note: If you did not receive a response message, it might be due to a network timeout. Please change the paymentRequestId and call the API again to resolve the issue.

Step 2: Redirect to the enrollment page (normalUrl)
Client-side

After the merchant server obtains normalUrl and passes it to front end, it will redirect from the merchant front end to the enrollment page.
Web
if (serverResponse.normalUrl != null) {
  window.open(serverResponse.normalUrl, '_blank');
}
WAP
window.location.href = URL;
iOS
import SafariServices

// After receiving normalUrl from your backend
func redirectToSubscription(normalUrl: String) {
    guard let url = URL(string: normalUrl) else { return }

    // Option A: Open in SFSafariViewController (recommended, stays in-app)
    let safariVC = SFSafariViewController(url: url)
    present(safariVC, animated: true)

    // Option B: Open in external browser
    // UIApplication.shared.open(url)
}
Android
import android.content.Intent
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent

// After receiving normalUrl from your backend
fun redirectToSubscription(normalUrl: String) {

    // Option A: Open in Chrome Custom Tabs (recommended, stays in-app)
    val customTabsIntent = CustomTabsIntent.Builder().build()
    customTabsIntent.launchUrl(this, Uri.parse(normalUrl))

    // Option B: Open in external browser
    // val intent = Intent(Intent.ACTION_VIEW, Uri.parse(normalUrl))
    // startActivity(intent)
}

Step 3: Obtain the enrollment result
Server-side

You can obtain the enrollment result using one of the following methods:
  • Receive asynchronous notifications from Antom
  • Inquire about the enrollment 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 creation notification to the webhook URL you set. You need to store the subscriptionId for subsequent subscription payment initiation. 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 subscriptionNotificationUrl in the create 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.
Notes:
  • If you specify this URL in both this API and Antom Dashboard, the URL configured in the API takes precedence.
  • Once the initial enrollment is completed, subscription deductions cannot be initiated on the same day; they can only be initiated the following day.
The following code shows a sample of the asynchronous notification request:
{
  "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"
}
  1. Verify the asynchronous notification
When you receive an asynchronous notification from Antom, you are required to return the response in the Sample codeformat, 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 enrollment is 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 enrollment result

You can also inquire about the enrollment result by calling the inquireSubscription API using subscriptionId or subscriptionRequestId from the enrollment request.
The following sample code shows how to call the inquireSubscription API:​
public static void inquireSubscription() {
  AlipaySubscriptionInquiryRequest request = new AlipaySubscriptionInquiryRequest();
  // set your subscriptionId
  request.setSubscriptionId(subscriptionId);

  // Inquire subscription
  AlipaySubscriptionInquiryResponse 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 subscriptionId
{
  "subscriptionId": "20260119110000000000000910000006774"
}
using subscriptionRequestId
{
  "subscriptionRequestId": "SUBSCRIPTION_20260120004816541_AUTO"
}
The following sample code shows a response message:
{
  "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"
  }
}
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
S
Indicates that this API is called successfully and the normalUrl is returned.
You can obtain the enrollment result from the subscriptionStatus parameter in the inquireSubscription API response.
F
Indicates that this API call is failed. The normalUrl is not returned.
For more information about the failure reason, refer to result.resultCode.
U
Indicates that the API call status is unknown. Retry the calling process.
Use the same subscriptionRequestId or subscriptionId to try again.

After enrollment

After completing the enrollment, you can perform the following actions:

Initiate subscription deductions
Server-side

Once the user confirms their enrollment, you need to store the subscriptionId for subsequent subscription deductions initiation. For details, please refer to Initiate subscription deductions.

Subscription cancellation
Server-side

The subscription cancellation feature allows buyers and you to cancel the current subscription at any time when the associated service is no longer needed. For more details, please refer to Cancel subscription.