Updated Documentation for adding recurring support to a payment gateway

Hi,

I've found #459540: Documentation for adding recurring payment support to a payment gateway module to be useful, but already recognize that it is out of date. I'm implementing recurring payments on at least one gateway (eprocessingnetwork) and looking at the api docs for another (nmi), and am trying to figure out which hooks I need to implement. I'm seeing 3 different approaches for handling recurring fees, and I'd like to make sure uc_recurring supports them...

I'd just like some confirmation that I'm taking the right approach here, and implementing the right hooks....

Approach 1: ARB-style - Gateway allows posting of arbitrary recurring payments, then repeats until canceled or number of payments reached. Gateway returns id to be stored locally for future cancellation. Repeating fee generally cannot be modified--must be canceled and a new one added if amounts change, with the exception of updating card expiration dates.

Approach 2: Recurring product created on gateway, and requested through API. This is the only type of recurring payment the NMI gateway supports. eProcessingNetwork also supports this, slightly differently. With this model, a user needs to log into the payment gateway web site and set up a recurring payment type. In epn, this is a recurring schedule, price not necessary--you just pass the recur id into the gateway and it follows the rules configured there. In NMI, this is an actual product with a price, and a corresponding product sku must be passed into the gateway to trigger the recurring order.

Approach 3: CIM-Style. Credit card/customer info is stored in the gateway, so that it can be referenced with a specific transaction id. No payments are actually scheduled on the gateway--the recurring billing is triggered by uc_recurring. UC recurring stores this detail in the fee object, and initiates a new charge without needing actual credit card info--it just uses the transaction id to refer to the stored data at the gateway. This allows for varying charges/varying schedules to be implemented.

So... The epn gateway supports all 3 of those methods. NMI only supports #2. #1 and #2 usually involve a post back to the server whenever a recurring payment is actually attempted, and it seems that we should be able to update the fee object when this happens.

Here's what I'd like confirmation about, that these are the functions to implement:

1. uc__recurring_info - set module to uc_recurring, provide fee handler (module name), renew callback, and process callback, optional cancel callback, menu items. Set "own handler" for approaches #1 and #2.

2. uc__process -- called with an order object and a fee object to initiate a new recurring fee, once for each product in the order that is marked as recurring. Update the $fee->data array with any data you want to store for the future. Return TRUE if successful.

3. uc__renew -- called when uc_recurring processes renews. For approaches #1 and #2 above, return TRUE if successful. For #3, process the actual charge and return TRUE if successful.

4. uc__cancel -- callback for if a user cancels a renewal fee

5. For approaches #1 and #2, implement a silent post menu callback that calls uc_recurring_renew with the fee object, and set it with some indication of success/failure that uc__renew can use to determine its return value.

Does that sound correct? Anything missing?

Thanks,
John