X-Cart:X-Payments Subscriptions and Installments - Revision history

Dohtur: /* Getting started with X-Payments Subscriptions and Installments */

2016-06-13T13:29:17Z

‎Getting started with X-Payments Subscriptions and Installments

Dohtur: /* Getting started with X-Payments Subscriptions and Installments */

2014-05-19T12:06:16Z

‎Getting started with X-Payments Subscriptions and Installments

Dohtur at 12:48, 26 February 2014

2014-02-26T12:48:23Z

Dohtur: Created page with '{{XC version|version=4.4.5|color=#FFB62F|comment={{{1|or above}}}}} ==Overview== X-Cart's X-Payments Subscriptions and Installments module is a full-featured recurring billing s…'

2014-02-26T12:11:43Z

Created page with '{{XC version|version=4.4.5|color=#FFB62F|comment={{{1|or above}}}}} ==Overview== X-Cart's X-Payments Subscriptions and Installments module is a full-featured recurring billing s…'

New page

{{XC version|version=4.4.5|color=#FFB62F|comment={{{1|or above}}}}}

==Overview==
X-Cart's X-Payments Subscriptions and Installments module is a full-featured recurring billing solution for stores based on X-Cart. If you are considering a subscription model for some or all of your products or services, the X-Payments Subscriptions and Installments module is the way to go:
:* Fully PCI compliant subscriptions for X-Cart with the help of the [[X-Payments:User_manual|X-Payments]] application.
:* Setting up a subscription is as easy as configuring a product.
:* Can be used for tangible goods, downloadable products, services - you name it. Selling expensive goods? Use subscriptions to allow your customers to pay in installments.
:* Possible to add a subscription setup fee (or make it free).
:* Flexible billing periods (weekly/monthly/annually, in a certain number of days/weeks/months or on a certain day of the week/month/year).
:* Recurring billing is fully automated and runs on its own.

::<videoflash>w5hiSvXPmp0|800|476</videoflash>

==System requirements and installation==

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

==Getting started with X-Payments Subscriptions and Installments==

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 your server to periodically run the xps_cron.php script (required for correct operation of the module):
#*[[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Running_the_script_xps_cron.php|Running the script xps_cron.php]]
# Log in to your store's Admin area and adjust the module configuration settings:
#* [[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/Provider experience|Admin/Provider 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: [[File:XPsubscr_configure.png|border]] The X-Payments Subscriptions and Installments module configuration page opens: [[File:XPsubscr_settings.png|border]] 
# Adjust the module configuration settings:
#* '''Number of rebill attempts for an unsuccessful charge''': Normally, the module will charge a subscription customer according to the schedule defined for their specific subscription. However, sometimes the processing of such payments may fail. In this case, the module will attempt to charge the customer's card again in a few days (The number of days is defined by the "How often to attempt rebills for an unsuccessful charge (in days)" setting below). The "'Number of rebill attempts for an unsuccessful charge" setting allows you 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. If this number is exceeded, the module will stop the subscription and send an email notification both to the customer and the store's orders department.
#* '''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''': The module can notify subscription customers that they will soon be charged for their subscription a few days before the subscription payment is actually billed to their account. The setting "Notify the customer of the upcoming payment X days in advance" allows you to specify how many days in advance the store must send a notification of the upcoming subscription payment to customers with active subscriptions.
# Click '''Apply changes'''. This is it. Now your module has been configured.

==Running the script xps_cron.php==

The module X-Payments Subscriptions and Installments provides a script xps_cron.php (for X-Cart versions 4.6.1 and earlier - cron_subscriptions.php) that must be periodically executed from the command line for correct operation of the module.

The tasks dependent on the execution of the xps_cron.php script include the following:
:* selection of subscriptions for which the following payment is due in N days, and sending the upcoming subscription payment notification to the customers, as per the module configuration settings;
:* selection of subscriptions for which the following payment is due on the current day, creating orders for such payments, processing the orders for payments that were successful and scheduling the day for the next re-bill attempt for the payments that failed;
:* tracking the number of failed attempts to charge the customer for the subscription and cancelling the subscription if the maximum allowed number of such attempts is exceeded;
:* tracking the number of successful payments for each active subscription and stopping the subscription when the expected number of billing periods, as per the subscription settings, is reached.

The recommended frequency for running xps_cron.php is once per day. You can launch this script using your favorite scheduling program (for example, [http://en.wikipedia.org/wiki/Cron | cron daemon] in Unix/Linux systems).

Recommended setup for running the xps_cron.php script via crontab:
<pre>
0 2 * * * cd /path/to/your/xcart; /path/to/php -d safe_mode=Off xps_cron.php --key=c901d65fc15ff15d0ac0af967437d051
</pre>
::* 0 2 * * * - to run the script every day at 2:00 AM
::* cd /path/to/your/xcart - to change dir to X-Cart folder on your server
::* /path/to/php - path to PHP 5.3.1 CLI binary on your server
::* -d safe_mode=Off - to execute cron_backup.php script
::* --key=c901d65fc15ff15d0ac0af967437d051 - secure key defined in X-Cart's [[X-Cart:General_Options|General Settings]] ("Secure key for launching the cron.php script")
 

==Admin/Provider experience==

===Setting up a subscription product===
Subscription products are set up the same way as any other product in your store's catalog. The only difference is that, when you create a subscription product, you need to select the option '''This is a subscription product''' in the product's details: 
:[[File:XPsubscr_product_checkbox.png|700px|border]] 
Once you have selected this option, the product details page is expanded with a few new fields: 
:[[File:XPsubscr_product_settings.png|700px|border]] 
You must adjust these fields to configure the subscription:
:* '''Setup fee''': ''(This replaces the product's '''Price''' field.)'' Enter a setup fee for your subscription. {{Note1|'''Note''': The product's selling price will be calculated as '''Setup Fee + Subscription Fee''' (see below). If you do not intend to charge any subscription setup fee to the buyer, set the Setup fee to "0" (zero); in this case, the product's selling price will equal the Subscription fee.}}
:* '''Billing period''': Set the frequency of recurring payments for the subscription.  ''Examples:'' "[Each] - [ 2 ]-th day of - [Week]" = Every Monday "[Each] - [ 2 ]-th day of - [Week] + Count days from the end" = Every Saturday "[Every] - [ 2 ]- [Week(s)]" = Biweekly "[Every] - [ 1 ] - [Year(s)]" = Once a year
:* '''Subscription fee''': Specify the amount that the buyer will need to pay for each period for the duration of the subscription. The Subscription fee cannot be "0" (zero).
:* '''Re-bill periods''': Specify the number of times that the buyer should be re-billed for this product after the initial payment (''This setting determines the duration of the subscription''). By default, this is set to 0, which corresponds to an infinite subscription.
After adjusting the subscription fields, be sure to save the changes.

===Viewing subscription orders===
You can easily find subscription orders using the "Search for orders" section in the store's back end. In the [+] More search options section of the search form, there is a '''Subscription''' field where you can specify the type of orders you wish to find. The available options are ''Show subscriptions only'', ''Show all orders'' and ''Show non-subscription orders only'':
:[[File:XPsubscr_order_search.png|border]] 

Subscription information for any specific order can be found in the Subscription Info section of the Order details page. 
The following information is provided:
:* Subscription status (Active/Stopped);
:* Next bill date (the date of the following expected payment);
:* "Find all orders for this subscription" link (can be used to access the full list of orders pertaining to the subscription).
There is also the Stop/Re-launch billing button which allows you to [[X-Cart:X-Payments_Subscriptions_and_Installments#Stopping.2FRe-starting_a_subscription|stop/re-start re-bills for the subscription]].
:[[File:XPsubscr_subscription_info.png|border]] 

===Stopping/Re-starting a subscription===
At any moment you can stop re-bills for any subscription. To do so, follow these steps:
# Open the details of any order pertaining to the subscription that needs to be stopped.
# In the "Subscription Info" section, click the '''Stop''' button below the subscription status: [[File:XPsubscr_stop_subscription.png|border]] 
Once you have stopped the subscription, the respective billing task will be deleted from cron job processing; the '''Stop''' button will change to '''Re-launch'''. 
To restart a previously stopped subscription, use the '''Re-launch''' button:
::[[File:XPsubscr_relaunch_subscription.png|border]] 

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

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: 
:[[File:XPsubscr_product.png|border]] 

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]] (If the setup fee is 0, then the product's price equals the subscription fee.) 

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''.

Subscription products can only be purchased using X-Payments payment methods that support tokenization. For this reason, 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]] 

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. 

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

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 Find all orders for this subscription link, the customer can quickly access all orders associated with the subscription.
:[[File:XPsubscr_subcriptions_list1.png|border]] 

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

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]] 

==Email notification templates==
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.

Starting with the module version for X-Cart 4.6.2, the following notification templates are available:

: 1. Notification about the change of subscription status (separate for customer and for orders department):
:: /skin/common_files/mail/xps_subscription_status_subj.tpl
:: /skin/common_files/mail/xps_subscription_status.tpl
:: /skin/common_files/mail/xps_subscription_status_customer.tpl
:: /skin/common_files/mail/html/xps_subscription_status.tpl
:: /skin/common_files/mail/html/xps_subscription_status_customer.tpl

:: This notification is sent if:
:: - the subscription has been stopped by admin (eml_xps_subscription_stopped_by_admin_info)
:: - the subscription has been stopped after a specified number of failed rebill attempts, as per the module configuration settings (eml_xps_subscription_stopped_info)
:: - the subscription has been restarted by admin (eml_xps_subscription_restarted_info)
:: - the subscription has been stopped after all the expected subscription payments have been successfully processed (eml_xps_subscription_finished_info)

:: In case of a successful subscription payment, a regular order invoice is sent.

: 2. Notification of the upcoming rebill (for customer only):

:: This notification is sent to customer a few days before the next subscription payment (the number of days is defined according to the module configuration settings).

:: /skin/common_files/mail/xps_upcoming_rebill_subj.tpl
:: /skin/common_files/mail/xps_upcoming_rebill.tpl
:: /skin/common_files/mail/html/xps_upcoming_rebill.tpl

[[Category:X-Cart modules]]

@@ Line 24: / Line 24: @@
 # Configure your server to periodically run the xps_cron.php script (required for correct operation of the module):
 #*[[X-Cart:X-Payments_Subscriptions_and_Installments#Running_the_script_xps_cron.php|Running the script xps_cron.php]]
-# Log in to your X-Cart store's Admin area and ensure that you have at least one payment method configured for a payment gateway that supports [[X-Payments:User_manual#Tokenization_and_Re-Use_of_Saved_Credit_Cards_.28X-Payments_2.0_and_X-Cart_4.6.1_or_later.29|tokenization]], and this payment method has the "Use for recharges" option enabled in its settings:
+# Log in to your X-Cart store's Admin area and ensure that you have at least one payment method configured for a payment gateway that supports tokenization, and this payment method has the "Use for recharges" option enabled in its settings:
 #* [[X-Payments:User_manual#Enabling_Payments_with_Saved_Credit_Cards|Enabling Payments with Saved Credit Cards]].
 # Adjust the X-Payments Subscriptions and Installments module configuration settings:

@@ Line 24: / Line 24: @@
 # Configure your server to periodically run the xps_cron.php script (required for correct operation of the module):
 #*[[X-Cart:X-Payments_Subscriptions_and_Installments#Running_the_script_xps_cron.php|Running the script xps_cron.php]]
-# Log in to your store's Admin area and adjust the module configuration settings:
+# Log in to your X-Cart store's Admin area and ensure that you have at least one payment method configured for a payment gateway that supports [[X-Payments:User_manual#Tokenization_and_Re-Use_of_Saved_Credit_Cards_.28X-Payments_2.0_and_X-Cart_4.6.1_or_later.29|tokenization]], and this payment method has the "Use for recharges" option enabled in its settings:
 #* [[X-Cart:X-Payments_Subscriptions_and_Installments#Configuring the module|X-Payments Subscriptions and Installments: Configuring the module]]

@@ Line 21: / Line 21: @@
 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]]
+#*[[X-Cart:X-Payments_Subscriptions_and_Installments_module_installation|X-Payments Subscriptions and Installments module installation]]
 # Configure your server to periodically run the xps_cron.php script (required for correct operation of the module):
-#*[[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Running_the_script_xps_cron.php|Running the script xps_cron.php]]
+#*[[X-Cart:X-Payments_Subscriptions_and_Installments#Running_the_script_xps_cron.php|Running the script xps_cron.php]]
 # Log in to your store's Admin area and adjust the module configuration settings:
-#* [[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Configuring the module|X-Payments Subscriptions and Installments: Configuring the module]]
+#* [[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.
 <br /><br />
 Instructions for using the X-Payments Subscriptions module are available here:
-:* [[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Admin/Provider experience|Admin/Provider experience]]
+:* [[X-Cart:X-Payments_Subscriptions_and_Installments#Admin/Provider experience|Admin/Provider experience]]
-:* [[Draft:X-Cart:X-Payments_Subscriptions_and_Installments#Customer experience|Customer experience]]
+:* [[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.
+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_module_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.
@@ Line 46: / Line 46: @@
 '''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.
@@ Line 61: / Line 61: @@
 #* '''Number of rebill attempts for an unsuccessful charge''': Normally, the module will charge a subscription customer according to the schedule defined for their specific subscription. However, sometimes the processing of such payments may fail. In this case, the module will attempt to charge the customer's card again in a few days (The number of days is defined by the "How often to attempt rebills for an unsuccessful charge (in days)" setting below). The "'Number of rebill attempts for an unsuccessful charge" setting allows you 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. If this number is exceeded, the module will stop the subscription and send an email notification both to the customer and the store's orders department.
 #* '''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''': The module can notify subscription customers that they will soon be charged for their subscription a few days before the subscription payment is actually billed to their account. The setting "Notify the customer of the upcoming payment X days in advance" allows you to specify how many days in advance the store must send a notification of the upcoming subscription payment to customers with active subscriptions.
 # Click '''Apply changes'''.<br />This is it. Now your module has been configured.
 ==Running the script xps_cron.php==
 The module X-Payments Subscriptions and Installments provides a script <u>xps_cron.php</u> (for X-Cart versions 4.6.1 and earlier - <u>cron_subscriptions.php</u>) that must be periodically executed from the command line for correct operation of the module.
 The tasks dependent on the execution of the <u>xps_cron.php</u> script include the following:
@@ Line 123: / Line 123: @@
 ==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 />
@@ Line 129: / Line 129: @@
 :[[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 />
@@ Line 150: / Line 150: @@
 :[[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 />