X-Payments:Recurring Billing in Magento with X-Payments

Recurring payments with Magento and X-Payments: General information

Using Magento integrated with X-Payments allows you to accept recurring payments. This feature is intended for businesses that wish to sell subscription products or to allow their clients to pay for products or services in installments. We will refer to both of the above as "subscriptions".

A subscription can be set up in Magento by creating a product with a recurring profile. A recurring profile is a set of parameters according to which a purchaser of the product should be charged for it. For example, these parameters specify the date on which payments for the subscription should start, the subscription duration, the frequency with which the customer should be charged during this period, whether there should be any kind of initial fee and so on.

When a customer purchases a subscription product, they authorize the store to charge their payment card according to the payment schedule defined in the respective recurring profile.

Payments on recurring profiles are performed using the same payment processor that you you use to process regular, non-recurring payments (the one for which you have a payment configuration in X-Payments).

Note that in Magento products with recurring profiles are considered nominal items. On the shopping cart page and during checkout the totals for nominal items (including the nominal subtotal termed "Regular Payment", tax and shipping), as well as the nominal grand total are calculated and displayed separately from regular products - under the Nominal Items header.

When an order is created for a product with a recurring profile, a record is created for the respective subscription that is submitted to a special script run periodically by cron job and checking whether it is time for the next payment on any recurring profile. When the script goes through this record for the first time, the subscription is activated. If the initial fee parameter is set for the subscription, the script initiates an authorization or capture of the sum equal to "initial fee + initial fee tax". If the current date is equal to or greater than the start date defined for the subscription, an authorization or capture of the payment for the first subscription period also takes place. If the subscription start date has not yet been reached, the charge for the first subscription period does not take place - it will be performed on a later date.

Accordingly, orders containing subscription products are processed as follows:

If the order contains a single subscription product (no other regular products or subscriptions), and this subscription product does not have a start date defined that is greater than the current date, then an authorization or capture on this subscription takes place at the time of order creation:

• If the subscription product does not have an initial fee defined, after completing the checkout process the customer is charged for the first subscription period, which is "subscription product subtotal (Regular Payment) + shipping amount + tax amount".
• If the subscription product has an initial fee defined, on checkout completion the customer is charged not only the sum for the first subscription period ("Regular Payment + shipping amount + tax amount"), but also the "initial fee + initial fee tax" amount (all in one payment transaction).

If the subscription start date is in the future, then for this subscription initially only the amount equal to "initial fee + initial fee tax" is charged (that, of course, provided that the initial fee parameter has been defined for the respective recurring profile). This charge results in a separate order. Later, when the subscription start date is reached, the amount corresponding to the payment for the first subscription period ("Regular Payment + shipping amount + tax amount") is authorized or captured.

If a subscription with a start date in the future does not have an initial fee defined, and this subscription is the only subscription in the order (the order contains no other subscriptions or regular products), on checkout completion only a transaction to authorize a small amount set using the "Setup minimum payment amount for recurring orders and customer card authorization actions" field takes place. An authorization of this small amount is needed to obtain a token that will be used later to charge further payments on this subscrition. An authorization or charge of the sum for the first subscription period ("Regular Payment + shipping amount + tax amount") for this subscription takes place later - according to the payment schedule defined for this subscription in the recurring profile of the respective product.

There are two cases in which the activation of a purchased subscription happens with a delay. That is when the subscription is purchased in the same order with non-recurring products or with other subscriptions.

When a subscription is purchased along with regular, non-recurring products, at the time of order creation the customer is charged only for the regular products. An authorization or capture of the subscription payment happens later when a special script run by cron activates the subscription and initiates the respective payment. By default this script is run every 2 hours. You can readjust the frequency by tweaking the cron_expr parameter in the file app/code/community/Cdev/XPaymentsConnector/etc/config.xml of your Magento store project.

When multiple subscriptions are purchased simultaneously, at checkout the customer is charged only for one of the subscriptions. Payments for the rest of the subscriptions that have been purchased take place at a later time - after the respective subscriptions are initialized by the special script mentioned above.

This means that if a customer's cart contains both subscriptions and non-recurring products, and the number of subscriptions in the cart is more than one, after completing checkout the customer is charged according to the following algorithm:

1. First, the customer is charged for all the non-recurring products. A separate order is created for this payment.
2. The cron-activated script initializes the purchased subscriptions one by one and starts charging the customer according to their respective recurring profiles:
   • If a subscription has an initial fee defined and starts on a date that is later than the date on which the order was created, the initial fee and the respective initial fee tax are charged. A separate order is created for this payment. (If the subscription start date coincides with the date on which the order was created, the customer is charged for a sum that includes the payment for the first subscription period, the initial fee and the initial fee tax simultaneously).
   • After this a payment for the first subscription period is charged for each of the purchased subscriptions - according to their start dates. Also, recurring subscription payments are charged for the following subscription periods as these periods start. The process goes on until the last subscription has been completed, i.e. until all the payments that need to be charged for each of the purchased subscriptions have been charged successfully. Each subscription payment for each of the purchased subscriptions makes a separate order.

Gradually charging the customer by cron if they purchase a subscription along with non-recurring products or other subscriptions was implemented on purpose. First, this is conditioned by the architecture of Magento itself, which requires that a separate order be created for each product with a recurring profile that is purchased. Second, this is related to the payment systems' limitation on the use of saved credit card tokens during a certain period (If you have used a token for a payment, the next time they allow you to use this token is, for example, no earlier than in two minutes. The exact duration time of the delay depends on your payment system).

If your store uses discounts, they may be applied to products with recurring profiles. Please be aware that a discount is applied only to the first subscription payment and is not applied to the initial fee amount or the amounts of any subscription payments following the first one.

The payment mode for recurring payment transactions is defined by the same settings that determine the mode for conducting regular payment transactions via X-Payments.

• If in the payment configuration settings in X-Payments the "Initial transaction" setting is set to Auth and capture (whereas in Magento the setting "Use forced authorize operation" is set to No), then recurring payments at your store will be conducted as sale type transactions (with authorization and capture both done at the same time).
• If in the payment configuration settings in X-Payments the "Initial transaction" setting is set to Auth, or the setting "Use forced authorize operation" in Magento (System > Configuration > Payment methods > X-Payments connector) is set to Yes (The value of this setting overrides the "Initial transaction" setting in X-Payments), then recurring payments at your store are done as authorization only. This means you have to capture each payment manually.

The payment mode for the initial fee and the initial fee tax can be set up separately from the payment mode for regular subscription payments.

• If in X-Payments the "Initial transaction" setting is set to Auth, or the setting "Use forced authorize operation for initial fee" in Magento is set to Yes, then the charge for the sum corresponding to "initial fee + initial fee tax" is performed as an authorization.
• If in the payment configuration settings in X-Payments the "Initial transaction" setting is set to Auth and capture (whereas in Magento the setting "Use forced authorize operation for initial fee" is set to No), an automatic capture of the required sum is performed.

Admin experience

Setting up products with recurring profiles

By default recurring profiles can be set on simple and virtual products. If you need to be able to set recurring profiles on other product types as well, do the following:

1. In the Admin Panel of your Magento store, go to Catalog -> Attributes -> Manage Attributes.
   
   
   
2. In the list, locate the attribute is_recurring and click on its name to access its properties.
   
   
   
3. On the Attribute Properties panel, go to the Apply To field and add the product type for which you want to allow recurring profiles.
   
   
   Save this change.
   
   
   
4. Go back to the list of attributes and locate the attribute recurring_profile.
5. The same way you did it for is_recurring, add the desired product type in the Apply To field in the properties of the recurring_profile attribute.

Once you have completed the above steps, you should be able to set recuccing profiles on the products of the type you have added.

To create a product with a recurring profile, do the following:

1. In the Admin panel, navigate to Catalog -> Manage Products.
   
   
   
2. At the top right-hand corner of the page that opens, click the Add Product button.
   
   
   
3. Select the attribute set and the product type for your new product by adjusting the Attribute Set and Product Type fields.
4. Click Continue. This opens the product editor where you need to specify the details of your product.
5. Provide all the necessary information about the product (name, description, price, tax class, etc.)
6. Switch to the Recurring Profile tab.
7. Set Enable Recurring Profile to Yes.
8. Use the section that expands below to complete the product's recurring profile. The parameters that can be processed by X-Payments are as follows:
   • Customer Can Define Start Date: Select Yes if you want to allow customers buying this product to choose the date on which the recurring payments for the product will start. Select No if you want the recurring payments to start on the date of purchase.
   • Maximum Payment Failures: Specify the number of scheduled payments that can fail before the profile is automatically suspended.
   • Billing Period Unit: (required) Specify the unit for billing the customer during the subscription period (Day, Week, Two weeks, Month or Year).
   • Billing Frequency: (required) Specify how often within the billing period unit specified above a payment transaction for the recurring profile should be initiated. For example, if you want a payment transaction to be initiated biweeky, set the Billing Period Unit value to "Two weeks" and the Billing Frequency value to "1".
     Comment: The above two values are used to calculate the length of a Billing Cycle: 1 Billing Cycle = "Billing Period Unit" / "Billing Frequency"
     For example, if the Billing Period Unit is "Two weeks" and the Billing Frequency is "1", then the Billing Cycle is 14 days.
   • Maximum Billing Cycles: Specify the maximum number of billing cycles allowed for the subscription. Leave the field blank if you want the recurring profile to be permanently active. (In the latter case, the customer will be charged for the subscription until the recurring profile is suspended or canceled.)
     Example: In order to set up a subscription for one year with monthly subscription payments, adjust the product’s recurring profile parameters as follows:
     

   • Billing Period Unit = "Month"
   • Billing Frequency = "1"
   • Maximum Billing Cycles = "12"

   • Initial Fee: Specify the amount that the customer should be charged as soon as the subscription is purchased. The initial fee is paid only once during the life of a subscription.
9. Click the Save button to save your settings.

That's all. A product with recurring profile has been created.

Viewing and managing subscriptions

You can view the subscriptions that have been purchased at your store. It is possible to view all your store's subscriptions or just the subscriptions of a specific customer.

To view all your store's subscriptions:

• In the Admin panel, go to Sales -> Recurring Profiles (beta).
  
  
  You should be able to see the list of all your store's subscriptions:
  

To view all the subscriptions of a specific customer:

1. In the Admin panel, go to Customers -> Manage Customers.
   
   
   
2. In the list of your store's customers, locate the entry for the customer whose subscriptions you need to view and click on it to access the customer's profile.
   
   
   
3. In the left-hand side menu, select the Recurring Profiles (beta) tab:
   
   
   You should be able to see the subscriptions of the customer you have selected:
   

In the subscriptions list, the column "Profile State" shows the current status for each subscription:

• Pending: The subscription has been created by the customer but has not yet been initialized by the cron-activated script.
• Active: The cron-activated script has initialized the subscription and now payments on this subscription are charged according to the recurring profile schedule.
• Finished: The subscription has expired.
• Canceled: The Max failure count for the subscription has been reached.

To view the details of a specific subsription, you need to locate it in the subscriptions list (use the filter at the top of the list to narrow your range) and click on the respective entry. This takes you to the Recurring profile view page:


On this page the Profile Information tab provides all the information about the created subscription, and the Related Orders tab allows you to access all the orders pertaining to the subscription.

If necessary, you can stop (cancel) any current subscription.
To cancel a subscription:

1. Locate the subscription that needs to be canceled and click to open its details in the Recurring profile view.
2. Click the Cancel button at the top right-hand corner of the screen:
   

Customer experience

If the parameter "Customer Can Define Start Date" was enabled in the recurring profile of a subscription product, customers can set the desired start date for the subscription on the product page:

After purchasing one or more subscriptions, a customer can view them in the Recurring Profiles section of their account:

It is possible to access all the orders for any specific subscription by clicking the Related Orders button on the page of the respective subscription:

A subscription can be canceled at any time by clicking the Cancel button