In the Subscription Payment process, the buyer selects a plan and payment method, goes through authorization to confirm information, and is then redirected to the authorization result page. You need to develop the subscription activation page during integration, which displays payment methods, redirects users to checkout with an authorization URL, and handles payment callbacks to redirect buyers based on the subscription status.

User experience

The payment experience for Subscription Payment is as follows:

Figure 1. User experience for Subscription Payment

The function of each section are as follows:

1. Subscription activation page: The buyer selects the subscription plan and payment method and confirms activation. A subscription order is generated. The buyer enters the subscription authorization process.
2. Authorization process: Redirect the user to the payment method authorization page, where the buyer confirms information, verifies their identity, and completes the authorization. Then the buyer is redirected to the Antom intermediate page.
3. Authorization result page: After completing the authorization, the buyer is automatically redirected to the authorization result page.
   

During the integration process, you need to focus efforts on developing the subscription activation page. This page serves the following purposes:

• Display available payment methods: Payment methods are sorted according to payment information, such as the payment amount and the buyer's region.
• Redirect the user to authorize: Redirect the buyer to the authorization page by using an authorization URL provided by Antom.
• Receive payment callback (optional): Receive the payment callback by monitoring the invocation of the page or by using a lifecycle function. Then you can redirect the buyer to the subscription result page according to the subscription status.

Integration steps

Start your integration by taking the following steps:

1. Obtain and display available payment methods.
2. Invoke the authorization process.

Step 1: Obtain and display available payment methods

Get the wallet name and logo, and display available payment methods on the page.

Get the wallet name and wallet logo

Contact Antom Technical Support to obtain the wallet name and logo corresponding to each payment method.

Filter payment methods

Before you display the payment methods, it is recommended not to display or disable payment methods that are undergoing maintenance to avoid subscription failures. You can contact Antom Technical Support to inquire about the maintenance status of payment methods.

Display payment methods

For Alipay+ payment methods, you must display the Alipay+ Partner logo. You can choose one of the following styles, ensuring each payment method names and logos is used correctly:

Step 2: Invoke the authorization process

You need to obtain an authorization URL first and then invoke the authorization process.

Intercept an invalid order

To avoid a repeated or expired subscription, it is recommended that you verify the status and validity period of the order after the buyer clicks or taps Subscribe now.

To intercept an expired subscription authorization, you can set the subscription expiration time by specifying the paymentExpiryTime parameter. If a buyer authorizes after the subscription expiration time, an error is reported. Setting the subscription expiration time also avoids repeated subscriptions, which might occur when the buyer authorizes long after they are redirected to the payment method page.

The time offset of a server can also lead to repeated subscription authorizations. It is recommended that you check statuses when receiving asynchronous notifications for subscription and payment statuses. If duplicate authorization occurs, use the cancel API to cancel the order.

Obtain an authorization URL

After the buyer clicks or taps Subscribe now, your client requests an authorization URL from your server, and then your server calls the create API to obtain an authorization URL and returns it to your client. Before the authorization URL is obtained after the request is sent, disable the Subscribe now button in case of repeated operations triggered by the user.

During the process of requesting an authorization URL, both client-side and server-side requests may fail due to network issues. It is recommended to set a timeout for the HTTP request in the client-side request to prevent buyers from waiting too long. If you fail to obtain the authorization URL, buyers need to be allowed to initiate the subscription authorization again.

The key fields in the subscription authorization request are as follows.

Proceed with the authorization process

The user experience of the authorization process is as follows:

Redirect to your result page

In the create API, you can set the authorization URL through the subscriptionRedirectUrl parameter. Depending on the following terminalType values, it is recommended to pass either an H5 URL or a deep link:

When the buyer completes the authorization, they are first redirected to the Antom intermediate page before being redirected to the merchant's page.

After the authorization is completed, Antom sends an asynchronous notification to subscriptionNotifyUrl to inform you whether the authorization is successful or not.

When you receive the notification from Antom, you must return a response by following the code sample of notifySubscription. If you do not return the response to Antom or the response is not received by Antom due to network issues, Antom automatically resends the asynchronous notification within 24 hours for up to eight times or until the correct response is received. The sending intervals are as follows: 0s, 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

Subscription scenario samples

Pay special attention to the parameters that are related to subscription periods and subscription starting time. These parameters define the subscription plan provided for the buyer.

Key parameters

You can manage the subscription period and recurring payment logic by configuring the following parameters in the create interface:

The subscriptionStartTime parameter sets the start time of subscription payments, while the periodRule parameter defines the billing interval of the subscription, thereby delineating a billing cycle.

Assuming subscriptionStartTime is 2023-08-01T08:00:00+8:00, periodRule.periodType is MONTH, and periodRule.periodCount is 1, the billing period is one month and recurring payment details are as follows:

If the deduction for the first subscription period is successful, Antom initiates deductions starting 24 hours before the start of each subsequent period, until the deduction is successful or 24 hours elapse.

If you receive a deduction failure notification for the second subscription period, you cannot initiate a deduction request for this period on your own. You need to call the cancel interface to cancel the buyer's subsequent subscription service.

The first payment is always executed when the buyer completes the subscription authorization, regardless of whether subscriptionStartTime is before or after the completion of the subscription authorization. Subsequent payments follow the billing cycle schedule, with Antom initiating the deduction 24 hours before the start of each cycle. If the deduction fails, Antom continuously retries for 24 hours until the payment is successful or the 24-hour period ends.

After a successful or failed deduction, you are to be notified with the payment status by an asynchronous notification. The address to receive the notification is specified in Antom Dashboard or the paymentNotificationUrl parameter in the create request.

Note: About the deduction failure:

• If the first deduction fails: the subscription authorization will fail and the subscription will not take effect.
• If the deduction fails in the subsequent payment cycles:

• The subscription status will not be changed and the subscription remains active.
• For failed deductions in a particular period, you cannot retry the deduction. However, a failed deduction in the current period does not affect the deduction for next periods.

Samples

By specifying the corresponding parameters, you can use Subscription Payment service for a lot of scenarios. The following samples show how to specify parameters in the create API for several typical subscription scenarios.

Common subscription

After a successful subscription authorization, the payment is deducted immediately. Subsequently, the payment is deducted every other period.

{
    "...": "...",
    "paymentAmount": {
        "currency": "PHP",
        "value": "1100"
    },
    "period": {
        "periodCount": 1,
        "periodType": "MONTH"
    },
    "subscriptionStartTime": "2023-08-01T08:00:00+8:00"
}

Pre-sale

After a successful subscription authorization, the payment is deducted immediately. However, the service will take effect at a future time, and subsequent payments are deducted every other period.

{
    "...": "...",
    "paymentAmount": {
        "currency": "PHP",
        "value": "1100"
    },
    "period": {
        "periodCount": 1,
        "periodType": "MONTH"
    },
    "subscriptionStartTime": "2023-08-08T08:00:00+8:00"
}

Subscription promotion

After a successful subscription authorization, the payment is deducted immediately and then following payments are to be deducted every subsequent month . The subscription fee for the first two periods is halved, and the subscription fee returns to normal from the third period.

{
    "...": "...",
    "paymentAmount": {
        "currency": "PHP",
        "value": "1100"
    },
    "period": {
        "periodCount": 1,
        "periodType": "MONTH"
    },
    "subscriptionStartTime": "2023-08-01T08:00:00+8:00",
    "trials": [
        {
            "trialStartPeriod": 1,
            "trialAmount": {
                "currency": "PHP",
                "value": "550"
            },
            "trialEndPeriod": 2
        }
    ]
}

Seven-day trial

The service takes effect immediately when the subscription is initiated. However, the first deduction will occur one week later, followed by subsequent deductions once every month.

{
    "...": "...",
    "paymentAmount": {
        "currency": "PHP",
        "value": "1100"
    },
    "period": {
        "periodCount": 1,
        "periodType": "MONTH"
    },
    "subscriptionStartTime": "2023-07-08T08:00:00+8:00",
    "trials": [
        {
            "trialStartPeriod": 1,
            "trialAmount": {
                "currency": "PHP",
                "value": "0"
            },
            "trialEndPeriod": 1
        }
    ]
}