UC Recurring Payments and Subscriptions

Last updated April 9, 2012. Created by webchick on September 10, 2010.
Edited by LinL, bisonbleu. Log in to edit this page.

About

The UC Recurring Payments and Subscriptions module allows you to add recurring payments to an Ubercart Product so that when an order is placed with that product, a payment schedule will be set up to charge the user a set amount on a regular interval.

Uses

Mark products as "recurring" billing

The module exposes a feature which can be added to any product to support recurring payments. There are lots of flexible options for the frequency of billing, payment methods accepted, and what to do if a recurring payment attempt fails.

Subscriptions

If used in tandem with the Roles Ubercart feature, this module can be used to sell paid subscriptions to websites.

Integration with third-party payment gateways

Support for Authorize.net and Paypal are included in the module. Additionally, a variety of other contributed third-party payment gateway modules exist that implement recurring payment support. Many of these are listed on the project page.

Recurring payment APIs

For module developers implementing payment gateway integration, there is an extensive set of hooks for handling recurring billing.

Overview

The package includes the following modules, which are listed under the "Ubercart - recurring" package:

Recurring Payments API (required)

Core module to enable recurring payment support in Ubercart. Manages the integration between Ubercart and recurring payment gateways that implement a recurring fee handler. This module does not do anything on its own. It requires a module that creates the recurring payments on specific events like the Recurring Product Fees or Recurring Order module.

Recurring Product Fees

This module allows users to specify recurring fees for products.

Recurring - Hosted Gateways

Recurring Fees handlers for hosted gateways - Authorize.net ARB and Paypal WPS (TODO: What does that mean, exactly?)

Recurring Order

This module allows users to specify entire orders to be re-billed on a periodic basis. Useful for getting a new stock of widgets every 30 days.

Tutorial

This tutorial will walk you through the process of creating a basic, subscription-based site. Note that UC Recurring is a very flexible module and doesn't necessarily require things like payment gateways and Ubercart products, but this is the most straight-forward way to demonstrate what the module can do.

1. First, enable all of the required modules to get recurring payments to work. This entails all of the "core" Ubercart modules, in addition to payment-related ones. We'll be using the "Test gateway" in this example to demonstrate how the module works, though in practice you'll likely want a different payment module.

   Go to Administer→Site building→Modules (admin/build/modules) and enable the following modules:

   • Other package
     • Token
   • Ubercart - core package
     • Cart
     • Conditional Actions
     • Order
     • Product
     • Store
   • Ubercart - core (optional) package
     • Payment
   • Ubercart - payment package
     • Credit Card
     • Test Gateway
   • Ubercart - recurring package
     • Recurring - Hosted Gateways
     • Recurring Payments API
     • Recurring Product Fees
2. Next, we need to create a product that we'd like to be billed on a recurring basis. Go to Create content→Product (node/add/product). Fill out the product's Name, Description, SKU, and Sell price and click the "Save" button.

   

3. On your new product node, click the "Edit" tab, and then the "Features" sub-tab. Here you will be given a choice of various features to add to your product. Choose "Recurring fee" and click "Add".

   

4. The recurring fee product feature offers a variety of configuration options:
   

   Applicable SKU

   Allows the billing set up to provide to only a single SKU or all SKUs for a given product.

   Recurring fee amount

   Here you can specify how much to charge on each recurring billing or renewal date. This is useful if, for example, your product has an initial $30 activation fee (the sell price), but thereafter costs $5 per month (billing period).

   Payment interval settings

   Here you can specify both the time to wait before charging a recurring fee, and also how often the fee should be charged: daily, monthly, weekly, etc.

   Number of billing periods

   Specify a maximum number of times to charge the recurring fee.

   Specify a regular interval of 1 month, leave the other settings alone, and then click "Save feature."

   

5. If all goes well, when returned to the Features sub-tab you should see notification that this product now has a recurring fee attached to it.

   

6. In order for a user to complete the checkout, we must set up a means of payment. Go to Administer→Store administration→Configuration→Payment settings→Payment methods (admin/store/settings/payment/edit/methods) and follow the instructions at Encryption Instructions to enable credit card encryption. Enter a directory under "Card number encryption key filepath" like "../keys".
7. Finally, configure the recurring payment settings under the "Recurring payments" tab here (admin/store/settings/payment/edit/recurring). Options at this screen include:
   

   Valid payment methods

   For customers purchasing products with recurring fees, select valid means of payment (e.g. Credit card).

   Recurring fee checkout form message

   Displays a message to the user on the checkout form if their cart contains products that support recurring billing. It's not a bad idea to remind them, since there's no other visual indication that this will happen.

   Action to take if recurring fee fails to process

   If the payment method is declined, what happens? You can choose to simply return a message and fail to complete the checkout, or to complete the checkout, granting an extension before attempting re-billing.

   For the purpose of this tutorial, enable the "Credit card (test_gateway)" as a valid payment method, and then click "Save configuration."

   

8. To test, navigate to the product page and click "Add to cart", then "Checkout". Fill out some dummy address information and credit card data of "4111111111111111", expiration [sometime in the future], CVV of "123". If you entered text in the "Recurring fee checkout form message" field, it will appear at the top of the page.

   Click "Review order" to be taken to an order summary, and "Submit order" to complete it.

   

9. To test that recurring billing is working, ensure your test user has "view own orders" permission (admin/user/permissions). Set your system clock to 1+ month ahead and run cron.php. Now, if you view your list of orders from My account→Orders, you should see two charges, each a month apart.

   

10. If your test user also has been granted "view own recurring fees" permission, you'll see a tab at My account→Recurring fees, where you'll find a list of all of your active subscriptions along with "cancel" links to end them.