Subscription Management Overview
PayPro Global helps you manage your subscription-based product/service access via dedicated webhooks and API.
Subscription Webhooks
To create a flawless customer experience, always stay in sync with the subscription webhooks. Our goal is to help you understand how PayPro Global manages the different phases of a subscription's lifecycle. Below you can find a diagrammatic representation of how your backend can be integrated with PayPro Global's subscription and webhooks.
Once you created a subscription product and provided the webhook URL in Product setup -> 1. Product -> IPN URL, you will automatically get the following webhook types:
| Type id | Type name | Description |
|---|---|---|
| 1 | OrderCharged | Triggered when an order has been successfully processed for the initial order of the subscription. |
| 6 | SubscriptionChargeSucceed | Triggered when a recurring payment (order) has been successfully processed. |
| 7 | SubscriptionChargeFailed | Triggered when a recurring payment (order) has failed. |
| 8 | SubscriptionSuspended | Triggered when a subscription has been suspended by the customer, vendor, or our Support Team (as per the customer's or vendor's request). |
| 9 | SubscriptionRenewed | Triggered when a subscription has been successfully renewed either by the customer or our Support Team (per the customer's or vendor's request). Triggered when a subscription has been terminated. |
| 10 | SubscriptionTerminated | Triggered when a subscription has been terminated. |
| 11 | SubscriptionFinished | Triggered when a subscription has ended. |
| 21 | SubscriptionPaymentInfoChanged (extended IPN) | Triggered when a) the customer updates his payment credit card details in the PayPro Global customer account b) the customer switches the payment method from PayPal to credit card in the PayPro Global customer account |
| 13 | TrialCharge | Triggered when a trial order has been processed. |
When the subscription is created, it gets a unique identifier which is
SUBSCRIPTION_ID=
It is the primary subscription parameter that we recommend saving in your database for you to be able to track different webhook types within one subscription as well as to be able to use it later when running API requests.
Subscription Created
When a customer successfully subscribes to your product, you will receive a webhook with the type OrderCharged where you will get
SUBSCRIPTION_ID=
parameter. Please store it for later use.
You will also receive the following subscription info:
| SUBSCRIPTION_STATUS_ID= |
|
| SUBSCRIPTION_STATUS_NAME= | Text representation of SUBSCRIPTION_STATUS_ID. |
| SUBSCRIPTION_NEXT_CHARGE_DATE= | Returns the subscription's next charge date. |
| SUBSCRIPTION_NEXT_CHARGE_AMOUNT= | Returns the subscription's reference next charge amount or billing next charge amount depends on the subscription's pricing configuration. |
| SUBSCRIPTION_NEXT_CHARGE_CURRENCY_CODE= | Returns the subscription's reference currency code or billing currency code depends on the subscription's pricing configuration. |
| SUBSCRIPTION_NEXT_CHARGE_CURRENCY= | Possible values 0, 1.
|
| SUBSCRIPTION_RENEWAL_TYPE= | Subscription renewal type. Variants: 1-Manual 2-Auto. |
| SUBSCRIPTION_INITIAL_ORDER_ID= | Order ID number for the initial charge of the subscription. |
| IS_ON_TRIAL_PERIOD= | Returns 1 if product has trial period, 0 otherwise. |
| TRIAL_PERIOD_TILL= | Returns trial period end date if product has trial period. |
| SUBSCRIPTION_NEXT_CHARGE_AMOUNT= | The reference next charge amount or billing next charge amount depends on the product pricing configuration. |
| SUBSCRIPTION_NEXT_CHARGE_CURRENCY_CODE= | Reference currency code or billing currency code depends on the product pricing configuration. |
| SUBSCRIPTION_NEXT_CHARGE_CURRENCY= | Possible values are 0 or 1.
|
| SUBSCRIPTION_NUMBER_OF_BILLING_CYCLES= | The billing cycle the customer is currently on. |
Store the information you need and grant product access to the customer until
SUBSCRIPTION_NEXT_CHARGE_DATE=
If you're offering a trial product and the customer decides to go with a trial at first, the system will trigger the TrialCharge webhook type, and you may want to give trial access to the product until
TRIAL_PERIOD_TILL=
Rebilling
You will receive the SubscriptionChargeSucceed event for each successful subscription payment. You will get
SUBSCRIPTION_ID=
parameter and update the corresponding subscription records in your database
SUBSCRIPTION_STATUS_ID=
SUBSCRIPTION_NEXT_CHARGE_DATE=
If
SUBSCRIPTION_STATUS_ID=1
SUBSCRIPTION_STATUS_NAME=active
remains active, continue allowing your customer access to the product/service until
SUBSCRIPTION_NEXT_CHARGE_DATE=
Due to the nature of recurring payments, sometimes they can fail for different reasons (expired payment details, insufficient funds etc.) In case of a failed subscription payment, you will get a SubscriptionChargeFailed webhook. By default, the system will make in total three attempts (one in 2 days). If all are unsuccessful, you'll get both SubscriptionChargeFailed and SubscriptionSuspended events for the last failed attempt to charge the customer. When a rebill fails for the first two times, the subscription status remains active.
SUBSCRIPTION_STATUS_ID=1
SUBSCRIPTION_STATUS_NAME=active
When the last attempt fails, the subscription gets the suspended status and you'll get
SUBSCRIPTION_STATUS_ID=2
SUBSCRIPTION_STATUS_NAME=Suspended
in the **SubscriptionSuspended ** event. You can revoke product access for the customer.
Upon each failed attempt, we will send a customer notification, and if he updates his payment details and the charge goes through, you'll get SubscriptionChargeSucceed. Product/service access can be granted until the
SUBSCRIPTION_NEXT_CHARGE_DATE=
Subscription Canceled (Suspended/Terminated/Finished)
When a subscription gets a suspended/terminated/finished status, you will get one of the corresponding webhooks
IPN_TYPE_ID=8
IPN_TYPE_NAME=SubscriptionSuspended
IPN_TYPE_ID=10
IPN_TYPE_NAME=SubscriptionTerminated
IPN_TYPE_ID=11
IPN_TYPE_NAME=SubscriptionFinished
You will get a subscription status via
SUBSCRIPTION_STATUS_ID=
and you should allow the customer continued access to the product/service up until
SUBSCRIPTION_NEXT_CHARGE_DATE=
is due for suspended & terminated statuses. When you get the SubscriptionFinished webhook, there will be no future rebills, and the number of billing cycles has finished, the subscription is over, and you may cut product access.
The cancellation reason will be sent in
SUBSCRIPTION_CANCELLATION_REASON_ID=
and the cancellation remark provided in
ACTION_REASON=
Subscription Renewed
When a subscription has been successfully renewed either by the customer or our Support Team (per the customer's or vendor's request), you will receive the SubscriptionRenewed webhook, and the subscription status will be set to active
SUBSCRIPTION_STATUS_ID=1
SUBSCRIPTION_STATUS_NAME=active
If the subscription's due date
SUBSCRIPTION_NEXT_CHARGE_DATE=
is in the past, then the charge will immediately take place. In case of a successful charge, you'll also get the SubscriptionChargeSucceed event, and you can restore access to the product. If it fails, then the subscription status will be back to suspended
SUBSCRIPTION_STATUS_ID=2
SUBSCRIPTION_STATUS_NAME=Suspended
and the SubscriptionChargeFailed event will be fired along with SubscriptionSuspended.
Subscriptions API
When the customer is enrolled with the subscription, in most cases it needs additional running since his requirements are changing based on his level of product usage. The client may want to upgrade/downgrade the plan, adjust the pricing, cancel and renew his subscription, and you always need to be prepared to act quickly to keep your customer's satisfaction as high as possible.
With PayPro Global, you can manage all these cases with our advanced API. We have dedicated methods for updating customer's subscription name, quantity, recurring price, billing period, renewal type, next payment date, or product:
Get the subscription list.
https://store.payproglobal.com/api/Subscriptions/GetList/
Update the subscription name.
https://store.payproglobal.com/api/Subscriptions/ChangeName/Update the subscription quantity taking into consideration current quantity and current subscription total price.
https://store.payproglobal.com/api/Subscriptions/ChangeQuantity/Update the recurring price.
https://store.payproglobal.com/api/Subscriptions/ChangeRecurringPrice/Update the billing cycle period.
https://store.payproglobal.com/api/Subscriptions/ChangeBillingPeriod/Update the subscription renewal type.
https://store.payproglobal.com/api/Subscriptions/ChangeRenewalType/Update the next charge date.
https://store.payproglobal.com/api/Subscriptions/ChangeNextPaymentDate/Update the subscription product.
https://store.payproglobal.com/api/Subscriptions/ChangeProduct/For products with trial, we can even change the date when the subscription trial period ends via api/Subscriptions/ChangeTrialPeriodDate.
You may want to cut the trial product access or, vice versa, extend it for the customer to get to know your product better.
The option to automatically cancel the subscription for the customer is essential to avoid possible future refunds and chargebacks because of unwanted rebill. Hence, we offer a few methods which will change the status of a subscription from active to suspended/terminated/finished based on your flow:
Suspend the subscription with the ability to renew it later.
https://store.payproglobal.com/api/Subscriptions/Suspend/Terminate the subscription without the ability to renew it later.
https://store.payproglobal.com/api/Subscriptions/Terminate/Stop the subscription.
https://store.payproglobal.com/api/Subscriptions/Finish/We can renew the subscription via API as well:
Renew previously suspended subscription - terminated subscription cannot be renewed.
https://store.payproglobal.com/api/Subscriptions/Renew/Also, if you're running a promotional marketing campaign for existing customers or want to keep a customer by offering a discount, you can use API methods to apply a discount to the subscription. It allows you to choose if you want to apply to one or all upcoming subscription payments:
Apply a discount to an existing subscription.
https://store.payproglobal.com/api/Subscriptions/ApplyDiscount/Apply an accumulative discount to an existing subscription.
https://store.payproglobal.com/api/Subscriptions/ApplyAccumulativeDiscount/If you are using custom fields to pass custom information to your database and you need to update it for a particular subscription, you can also do it with the help of API:
Change the subscription custom fields.
https://store.payproglobal.com/api/Subscriptions/ChangeCustomFields/For your convenience, we have 1 API method running, ready to provide you with subscription details when using them:
Get the subscription details.
https://store.payproglobal.com/api/Subscriptions/GetSubscriptionDetails/Notifications
Email notifications are sent for all subscription requests to inform customers of updates or changes received throughout a subscription lifecycle.
PayPro Global takes complete care of notifying your customers.
System will automatically send the pre-charge notification emails to the customer before the renewal comes.
This reduces the number of refunds/chargebacks as the user is aware of the upcoming charge.
For subscriptions with manual renewal, the backend will trigger the email that includes the link to the checkout page.
This will allow the customer to easily prolong his subscription with any payment method.
After each payment, including recurring ones, we will send the confirmation email with the invoice for the customer's convenience.
When we face difficulties while trying to charge the customer for his next billing cycle, the system will send a notification informing him about the steps that should be taken to fix the issue. This could be to contact their bank, update the credit card details or switch the payment option.
For each subscription cancellation or renewal action, we will also notify the customer via email with the details.
When managing subscriptions via API you also have the option to select whether you would like us to inform the customer about
these particular changes by parameter SendCustomerNotification: true / false
You can get detailed information about email management in our dedicated section here.