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
- Initiate an enrollment request
- Redirect to the enrollment page (normalUrl)
- 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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
- 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"
}- 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.
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.