Cancel subscription
After a subscription cancellation is initiated, subsequent scheduled deductions will also be cancelled. If the cancellation is initiated after 22:00 on the day before the payment due date (T-1), the deduction already scheduled for the next day will not be cancelled and will still be processed. Deduction notifications can be handled through the asynchronous notification mechanism used for payment cancellation.
Initiate cancellation on the merchant side
In this scenario, you provide an entry point in your own app or website for users to cancel their subscriptions. When a user clicks to cancel subscription, your backend system calls Antom’s cancel API to process the cancellation and update the subscription status accordingly.
Step 1: Initiate a cancellation request Server-side
Call the cancel API to cancel a subscription. The following are key parameters for initiating a cancellation request:
Parameter name | Required | Description |
subscriptionId | No | 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. |
subscriptionRequestId | No | The unique ID assigned by a merchant to identify a subscription request. |
cancellationType | Yes | The cancellation type for the subscription. Valid values are:
|
public static void cancelSubscription() {
AlipayCancelSubscriptionRequest cancelSubscriptionRequest = new AlipayCancelSubscriptionRequest();
cancelSubscriptionRequest.setSubscriptionId(subscriptionId);
cancelSubscriptionRequest.setSubscriptionRequestId(subscriptionRequestId);
cancelSubscriptionRequest.cancellationType("CANCEL");
}The following shows the sample code of a request:
{
"subscriptionId": "20221215190000000000000040000",
"cancellationType": "CANCEL"
}Note: For Automatico PIX, the cancellationType TERMINATE is not supported.
The following shows the sample code of a response:
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}The table below shows the possible values of result.resultStatus in the response. Please handle the result according to the guidance provided:
resultStatus | Description | Further action |
S | The cancellation request has been accepted. | Indicates the cancellation request is initiated successfully, please refer to the "Step 2: Obtain the cancellation result" to retrieve the cancellation result. |
F | The cancellation failed. | |
U | The cancellation is unknown. | Resend the API request with the same value of paymentRequestId. Contact Antom Technical Support if the value of result.resultStatus is still U after three consecutive retries. |
Step 2: Obtain the cancellation result
Once the subscription is canceled, Antom will use the notifySubscription API to send you an asynchronous notification to the subscriptionNotifyURL which passed in during the enrollment request, and the buyer’s wallet access token will also expire.
The following code shows a sample of the asynchronous notification request:
{
"periodRule": {
"periodType": "MONTH",
"periodCount": 1
},
"subscriptionEndTime": "2023-11-06T08:00:00-08:00",
"subscriptionId": "20221205190000000000000450000007269",
"subscriptionRequestId": "amsmdsubscription_20221206_033332_074",
"subscriptionStartTime": "2022-10-04T09:00:00-07:00",
"subscriptionNotificationType": "CANCEL"
}Initiate cancellation in bank app
When buyers no longer need a particular service, they can freely cancel their subscription and decide whether to renew it based on their own needs, providing more flexibility and control in account management. Once the subscription is canceled, Antom will use the notifySubscription API to send you an asynchronous notification to the subscriptionNotifyURL which passed in during the enrolment request, and the buyer’s wallet access token will also expire.
The following code shows a sample of an asynchronous notification, which contains the following parameter:
- subscriptionNotificationType: The notification type about the subscription.
- CREATE: indicates that the subscription was created.
- CHANGE: indicates that the subscription was changed.
- CANCEL: indicates that the subscription is canceled and the service is not provided after the current subscription period ends.
- TERMINATE: indicates that the subscription is terminated and the service is not provided.
- UPDATE: indicates that the subscription was updated.
{
"periodRule": {
"periodType": "MONTH",
"periodCount": 1
},
"subscriptionEndTime": "2023-11-06T08:00:00-08:00",
"subscriptionId": "20221205190000000000000450000007269",
"subscriptionRequestId": "amsmdsubscription_20221206_033332_074",
"subscriptionStartTime": "2022-10-04T09:00:00-07:00",
"subscriptionStatus": "ACTIVE",
"subscriptionNotificationType": "CANCEL"
}If subscription cancellation involves a refund, for example, when a buyer requests a refund due to a complaint, you can call the refund API to process the refund.