View source for Draft:X-Cart:X-Payments Subscriptions and Installments

==Overview==

==System requirements and installation==

See [[X-Cart:X-Payments_Subscriptions_and_Installments_module_installation|X-Payments Subscriptions and Installments module installation]]


==Getting started==

To begin using the X-Payments Subscriptions and Installments module on your system:
# Ensure that your system meets the module system requirements, then install and enable the module:
#*[[Draft:X-Cart:X-Payments_Subscriptions_and_Installments_module_installation|X-Payments Subscriptions and Installments module installation]] 
# Configure the module:
#* [[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Configuring the module|X-Payments Subscriptions and Installments: Configuring the module]]

Once these steps are completed, the module is ready to use. 

Instructions for using the X-Payments Subscriptions module are available here:
:* [[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Admin experience|Admin experience]]
:* [[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Customer experience|Customer experience]]

==Activating and deactivating the module==

It is possible to temporarily disable (deactivate) the installed X-Payments Subscriptions and Installments module. Deactivation stops the module from operation, but it does not remove any settings you made to the module configuration nor clear any data that was generated during the period that the module was in operation. If you wish to completely remove all the data related to using the module, you need to uninstall it. See [[X-Cart:X-Payments_Subscriptions_and_Installments_mmodule_installation#Uninstallation|X-Payments Subscriptions and Installments: Uninstallation]] for more info.

'''To disable the module''':

# Go to the Modules section of your store's Admin area (Settings menu->Modules).
# Locate the entry for the X-Payments Subscriptions and Installments module and unselect the respective check box on the left. 
# Depending on the version of X-Cart you are using, you may need to apply the change by clicking the '''Apply changes''' button. The module will be disabled.

If the module X-Payments Subscriptions and Installments is installed, but not active, you can enable (activate) it.

'''To enable the module''':
 
# Go to the Modules section of your store's Admin area (Settings menu->Modules). This opens the list of your store's installed modules.
# Locate the entry for the X-Payments Subscriptions and Installments module and select the respective check box on the left. 
# Depending on the version of X-Cart you are using, you may need to apply the change by clicking the '''Apply changes''' button. The module will be enabled.

==Configuring the module==

After the module has been installed and enabled, it needs to be configured.

'''To configure the module''':

# In the Modules section of your store's Admin area (Settings menu->Modules), locate the entry for 'X-Payments Subscriptions and Installments' module and click the Configure link next to it:<br />[[File:XPsubscr_configure.png|border]]<br /><br />The X-Payments Subscriptions and Installments module configuration page opens:<br />[[File:XPsubscr_settings.png|border]]<br /><br />
# Adjust the module configuration settings:
#* '''Number of rebill attempts for an unsuccessful charge''': Use this to set the maximum number of times that your store must try to charge the customer's card after the initial attempt to process the subscription payment was unsuccessful.
#* '''How often to attempt rebills for an unsuccessful charge (in days)''': Specify how often your store must attempt to charge the customer's card again if the initial attempt to process the subscription payment was unsuccessful. For example, if you set this value to "3", your store will attempt to charge the customer's card once every three days - until the payment can be processed successfully.
#* '''Notify the customer of the upcoming payment X days in advance''': Specify how many days in advance the store must notify customers with active subscriptions of the next subscription payment. 
# Click '''Apply changes'''.<br />This is it. Now your module has been configured.

==Admin experience==

===Adding/Editing a subscription product===
[[File:XPsubscr_product_checkbox.png|700px|border]]<br /><br />
[[File:XPsubscr_product_settings.png|700px|border]]<br /><br />


===Searching for subscription orders===
[[File:XPsubscr_order_search.png|border]]<br /><br />

==Customer experience==
===Buying subscription products===
In your store's catalog, subscription products look similar to regular, non-subscription products: 
:[[File:XPsubscr_storefront.png|border]]<br /><br />

However, instead of the product's price, the product information for subscription products includes the product's setup fee and subscription fee. These can be seen both in the products list and on the product details page:<br />
:[[File:XPsubscr_product.png|border]]<br /><br />

In the shopping cart, the price of a subscription product is calculated as the sum of the product's setup fee and subscription fee: 
:[[File:XPsubscr_cart.png|border]]<br />(If the setup fee is 0, then the product's price equals the subscription fee.)<br /><br />

Subscription products use X-Cart's regular checkout routine, and the process of purchasing a subscription is the same as purchasing a regular product in X-Cart integrated with X-Payments. The only difference is that in the background X-Cart Connector passes a special attribute to X-Payments to mark this sale as ''using tokenization for future re-bills''.

As subscription products can only be purchased using X-Payments payment methods that support tokenization, all other payment methods, if they are used by the store, are automatically disabled for customers checking out with a cart containing a subscription product. At checkout, the customer’s credit card is stored and tokenized via X-Payments automatically, so you do not need to worry about PCI compliance issues.
:[[File:XPsubscr_checkout.png|border]]<br /><br />

Once the order is placed, the module adds a new subscription to cron job processing to bill the customer for this subscription according to the subscription related settings (Billing period, Subscription fee and Re-bill periods) in the details of the subscription product.

===Viewing subscriptions===
To review their subscriptions, customers use the Subscriptions tab in their accounts. Here they can find comprehensive information about all their subscriptions, including the ones that are currently active as well as the ones that have been stopped.<br />

The subscriptions are displayed as a list:
:[[File:XPsubscr_subcriptions_list.png|border]]<br /><br />

For each subscription the customer can find out the subscription status, the setup and subscription fees, the number of payments left, and the date of the next subscription payment.

By clicking on the <u>Find all orders for this subscription</u> link, the customer can quickly access all orders associated with the subscription.
:[[File:XPsubscr_subcriptions_list1.png|border]]<br /><br />

By clicking on the <u>Show calendar</u> link, the customer can view the subscription calendar: 
:[[File:XPsubscr_subcriptions_list2.png|border]]<br /><br />

The calendar shows the dates of the past and future payments related to the subscription and color-coded information about the status of each payment (The dates marked by green boxes mean successful payments, red boxes - failed payments, and blue boxes - future payments).
:[[File:XPsubscr_calendar.png|border]]<br /><br />

==Notifications==
The module X-Payments Subscriptions and Installments enables some specific notification messages (see below). To adjust the look/contents of these messages, edit the respective templates:

'''Subscription has been suspended after N rebill attempts''' (This notification is sent after the allowed number of rebill attempts, as per the module configuration settings, have been performed, but the payment still could not be processed):
: xps_subscription_stopped.tpl
: xps_subscription_stopped_customer.tpl
: xps_subscription_stopped_subj.tpl
: html/xps_subscription_stopped.tpl
: html/xps_subscription_stopped_customer.tpl

'''Subscription has been finished''' (This notification is sent after all the expected subscription payments have been successfully processed):
: xps_subscription_finished.tpl
: xps_subscription_finished_customer.tpl
: xps_subscription_finished_subj.tpl
: html/xps_subscription_finished.tpl
: html/xps_subscription_finished_customer.tpl

'''Upcoming payment in N days''' (This message notifies the customer of the upcoming rebill a few days in advance, as provided by the module configuration settings)
: xps_upcoming_rebill.tpl
: xps_upcoming_rebill_subj.tpl
: html/xps_upcoming_rebill.tpl