General information about subscription and lifecycle with suspension.
Your subscription can have multiple states:
Pending: A subscription is in the pending state when the subscription and subscription version is created.
Initializing: Once the subscription is created and no active token version is present the subscription will
switch into the initializing state until valid payment information are provided.
Active: As soon as the token can be charged the subscription switches into the active state.
Terminating: A subscription that is terminated but has outstanding charges or outstanding periods is in the
terminating state.
Terminated: Once all charges are carried out the subscription switches into the terminated state.
Failed: If the initialization of the subscription fails, the subscription will
automatically go into the failed state. This can also happen when the initial transaction
reaches the timeout. In case you are using the payment page or iframe integration
to initialize the subscription you need to keep this in mind. In case you want to
send an email with which the customer can initialize the transaction it is recommended
to use charge flows for the initial transaction as well.
Once a subscription has been created, a failure to pay an invoice becomes the most important event that could happen. Failures occur for many reasons:
Lack of an actual payment source on the associated customer
Attempt to use an outdated or expired payment source
An actual decline of an otherwise valid payment source
Once the payment fails it will trigger the standard charge flow to acquire valid payment information.
Inside the charge flow configuration you are able to set the charge flow levels to configure how many times
the payment information email is sent out. When the last charge flow level is reached and the subscriber
has not provided valid credentials the subscription switches into the suspended state.
Suspensions can be removed manually by opening the subscription and switching into the suspension tab. The outstanding amount will be charged with the next billing cycle.
|
Note
|
You can easily test a payment failure by creating a real subscription and then invalidating the token of the subscription. This will trigger automatically the payment failure process to update the token version. |
Subscriptions can be suspended. This can happen automatically if the outstanding amount can not be charged. Before this happens the associated charge flow has to reach the end without a successful payment.
Additional suspensions can be added manually. Essentially a suspension pauses the billing and it terminates the services temporarily. A suspension requires always an end date. The end date indicates when the suspension will be terminated. During the creation of the suspension the behavior after the suspension termination can be provided. That allows to define if the suspension reaches the end if the subscription should be terminated or if the subscription should be activated again. When the charge flow fails we create a suspension which will terminate the subscription after the suspension is terminated. Means we pause the subscription for the time of the suspension and if the subscriber does not contact the merchant within this time to reactivate the subscription we terminate afterwards the subscription because our assumption is that when the subscriber does not react on the e-mails sent with the reminder and if the pausing of the service does not trigger a reaction from the subscriber most probably the subscriber is not interested in the service anymore.
Suspensions can be added to a subscription via the backend. To do this you need to open the subscription and change into the suspension tab. There you are able to add suspensions to a subscription. For the time of the suspension no charges will be carried out. Once the subscription leaves the suspension and is not terminated the subscription will continue exactly where it was suspended.
A subscription can also be suspended automatically in case the charging of the outstanding amount fails and the payment information could not be retrieved via the Charge Flow. If a subscription is in suspension you should stop providing the service from your side. If the outstanding amount is not paid within the suspension period defined on the product using the charge flow link the subscription will be terminated automatically.
In case you subscription is in the termination state and you add a suspension to the subscription this will lead to
a suspension of the subscription and the date when the subscription will be terminated will be
postponed for the time of the suspension.
If a payment fails while charging, this will trigger a charge flow process based on your configurations. The subscriber will receive an email which will prompt the subsriber to update their payment information. In case you need more control over the email formatting and sending you can setup the charge flow in a way that your application is notified about a new charge flow email which should be sent. The application can with this take care of the sending. The charge flow documentation contains more details about how to setup this.
In case the subscriber should be able to update the payment details from within your application you might want to use the token update API call. This API operation creates a transaction which just updates the payment details for the token. The token can be found on the subscription object. See within the API documentation about the details for token update operation.
In order to do so, you need to update the token as follows:
Use the endpoint create transaction for token update. You provide the token that you want to update in the call.
This will create a transaction in pending state. Now use the transaction in your application to build the payment page or
to create an iframe checkout