Subscription Management is an optional function that can be defined within a gateway module. Its purpose is to remotely cancel a recurring subscription agreement with a payment gateway, manually and automatically. The stored Subscription ID value in WHMCS is then removed.
When a service is assigned to a payment gateway that implements this function (for example PayPal Subscriptions) and a Subscription ID is set, a Cancel Subscription button is displayed under the Products/Services tab in the admin area. Clicking it will trigger the API call defined in the _cancelSubscription function.
When the Automatic Subscription Management feature is enabled under Setup > General Settings > Invoices tab, a subscription will be cancelled automatically under the following circumstances:
- A cancellation request is submitted
- The order is cancelled or set to fraud via the admin interface of WHMCS
- The API is used to cancel or fraud an order with “cancelsub=true” passed
- An upgrade order is placed for the product/service
This feature should only be defined for payment gateways which create automatic recurring subscriptions that are processed outside of WHMCS (for example PayPal Subscriptions).
Implementation is a two-step process:
A subscription ID must be stored in tblhosting.subscriptionid for the given service in order for the cancel subscription function to be invocable. Typically this value should be set as part of a payment gateway callback routine (see callbacks)
Define the _cancelSubscription function in the gateway module file.
This function should contain the necessary API calls to cancel a recurring payment subscription at the payment gateway.
Return a "success" response to indicate successful subscription cancellation. The stored tblhosting.subscriptionid value is then removed. Any other response is considered a failure, and the subscriptionid value will remain in place.
An example of this function is shown in the sample gateway module at Sample Gateway Module