Treat recurring fees as new orders

Also if you apply the patch linked above #369742: CA predicates maybe don't need to be prevented from being evaluated more than once. you can test out the ability to automatically handle the renewal of roles if they are enabled on a product when a recurring fee is processed.

At the moment this patch is meant to just be a working proof-of-concept.

What torgosPizza said is correct, it is a re-work of the underlying process of how recurring payments are handled - so it will break existing recurring payment gateways, the creditcard test_gateway has been patched to show how it should work as an example.

When you test it out - processing an order for a recurring product with the test_gateway in this patch doesn't really do anything different to what was there before. But when it comes time to renew (you can just edit the database next_charge field to bring forward a renewal) you will see a new invoice in the users account and you will also see any roles attached to that product also get renewed automatically (without uc_recurring even being aware of the uc_roles module exists). This is what you get by treating a renewal as a new order and this is the same for any other module(s) that want to do something on a product being ordered/renewed.

uc_recurring shouldn't have any payment specific code in it and shouldn't care what payment method/gateway want to be able to process recurring payments - when a payment is due it just ask the original gateway if it wants to do anything at that point - some gateways will other will handle things themselve - eg. Paypal IPN

@aaronbauman Calling the payment method to handle the recurring fee is definitely a possibility (actually the more I think about the better it sounds - thanks for the feedback) - at the moment I just want to get something out that worked, the code definitely needs a lot more work - but I want to get an idea if what I was proposing had some support and worth me spending time on - which there looks like it might be.

Not sure if there was a problem with that original patch but I have re-rolled the patch against RC1 (and then tested it, so this patch should definitely work if you want to try again with the latest release)

Here is my second round of changes... focusing mostly on cleaning up the api's (I still consider the patch is a work-in-process, but it is fully functional and can be tested)

I realized something as I was going through the code, there are two types of functions that can be used to get modules to interact with each other:

1. hooks
2. callbacks

The difference is minor but significant, when calling a callback you are only interested in the results from one module while a hook is used to get results from any module that wants to do something at that point. Drupal itself doesn't really use callbacks much (if at all), this is really more used in a module like ubercart - example: even though you may have multiple gateways setup and running on the one site you are only interested in calling one of these when you process a payment not all of them. In the case of the recurring module it also just needs to find the one module to call at the right time to handle recurring functions.

In Drupal the convention for calling a hook is:

[hook]_[function]()   e.g. uc_order_menu()

While currently in ubercart the convention for using callbacks is either they are predefined in an array (e.g you query all the payment gateways modules to find out what is available and then find the specific callback from this array you need and call it). Or the other method of calling a callback in ubercart is with a syntax like:

[module]_[callback]_[function]()   e.g. [uc_order_pane]_$id_[show_edit]()

So with that in mind I was thinking if you had function(s) in your payment method/gateway module starting with uc_recurring it makes it obvious that those functions are specific callback solely for the purpose of handling recurring fees

So what I did was rename all the relevant functions so they were in this format (which means there is no need to pre-define the available callbacks before hand, we can just see if one is available at the time we need it and if so use it):

So what I setup was the following callback that any payment method can define to support setting up a recurring payments:

uc_recurring_[payment_method]_fee

A callback that allows a module to setup the recurring fee e.g. uc_recurring_credit_fee() and it just expects you to setup the recurring fee with the gateway, set the handler for future renewals and return TRUE/FALSE, the uc_recurring module takes over and actually adds the user fee information to the DB (this is something that Auth.net is doing at the moment and really shouldn't, it is the role of uc_recurring to setup the recurring fees in a standard way for any payment method)

The follow two callbacks are for fee_handlers to define (if they want):

uc_recurring_[fee_handler]_renew

A callback called on cron jobs to allow a gatway to jump in a do something at the time of renewal e.g. uc_recurring_test_gateway_renew()

uc_recurring_[fee_handler]_fee_ops

A callback that defines what operations are available to the admin and normal members, things like edit/update/cancel e.g. uc_recurring_test_gateway_fee_ops()

That basically is the guts of what is required to setup a recurring gateway.

As before the test_gateway has been patched to work with this new api as a working example, but I have also released a gateway (http://drupal.org/project/uc_securepayau) I am developing in conjunction with this for my own needs which also supports the above api's (as another example)

For my own needs I want to also get paypal subscriptions working with this same interface, although one of the problems with paypal is that ubercart first attempts to charge the payment and then sets up the recurring payment, with paypals subscription process you really need this all done in one step, so either recurring payment need to be setup in the payment charge step or the charge step skipped and everything processed in the recurring stage, anyone have any thoughts on what might be a better approach to standardize on for gateways like paypal where you need to do it all in one step?

Yes, now that uc_recurring has split from ubercart (core) I will need to split this patch into separate patches for ubercart and uc_recurring, although since I am free to commit these change directly into the uc_recurring 2.x-dev branch, I am hoping to get out a dev version shortly with these changes included so its easier for others to start doing some testing.

@grendzy this is exact what this feature is trying to solve. If recurring fees have there own order they would be treated like any other purchase appearing in a separate invoice and in a separate payment record for reports.

By a recurring fee just being another order other modules like uc_role, uc_shipping, uc_whatever can also act on every payment as they currently do when you place a new order.

@Sborsody you do bring up an issue I haven't really thought about. ie: when you want one module (e.g shipping) to only happen on initial order but not on subsequent orders/renewals, while you still want other modules to act on both the initial order and renewals/

What I have currently proposed in this issue should still work, because at least in your case you are selling two different products, ones the physical product with shipping and the second product is the subscription. So I think the way to handle this would be to setup two different product and if you want to sell them together create a product kit with both products combined.

Recreated the patch(es), this is exactly the same as the previous patch just split into two, one for uc_recurring and the other for ubercart.

The ubercart patch is only required to patch uc_credit and test_gateway to get the test_gateway working with this or other credit card processing gateway.

Thought I would show how easy it is to add a new payment method that supports this recurring api by creating a patch for uc_payment_pack to support recurring billing for check/cod/other payment methods as aaronbauman was wanting to do - all this does for those manual payment method is create a new invoice in the system and users account on each recurring billing date.

This change is part of the ubercart patch (along with the credit card test gateway patch), I have also made one small change to the uc_recurring patch, which just checks that a payment method actually supports the recurring option before allowing you to enable it on the settings page and use it for recurring billing.

I have committed the above patch for this module into the 2.x-dev branch.

Hopefully to try and make it a bit easier to get some testing and comments back.

To use it with the credit card test gateways or the one of the payment pack methods you will need to patch your ubercart module with the previous comment patch for ubercart.

yes you will need to do a little bit more work now then I originally posted (see comment #13 above), to get it working, especially if you want new orders to appear on your site for each renewal.

I have just re-worked some of the renewal section in uc_recurring to try and help support gateways like authorizenet and paypal (which I hope to work on at some point), this just mainly provides a new function:

uc_recurring_renew($fee);

This allows other modules to process a renewal in the same way that uc_recurring does in its cron job on the expire date of a fee.

The only reason we need to trace a recurring fee back to a product is so that when we create a new order we can put something in the actual order "product name" section on the invoice. I'm thinking to support more flexibly recurring fee functionality for example combining recurring fees we should add a 'name'/'title' field in the database so that we can setup the recurring fee name at the time of the original order and that will appear on every recurring order.

I have tracked down that problem in #28 and fixed it. We can't actually use model as this will be blank if you specify that a recurring fee should apply to all SKU's for a particular product.

I am now storing the original product information with the recurring fee so we can refer back to it at anytime in the recurring rebilling process.

I think I might close this issue, it started before uc_recurring was a separate project and all the changes to uc_recurring have been committed to the 2.x-dev branch.

I have opened separate issue for tracking the changes that need to happen to ubercart if you are using uc_credit or uc_payment_pack with uc_recurring, so that we can track these changes and when ready submit to the core ubercart project.

See #483494: changes to ubercart to work with uc_recurring