Sometimes an order needs to be processed on a recurring basis. In Payments, an order can have a recurring period set that will cause it to be duplicated and processed on a defined interval.

Setting Recurring Intervals

You can set a recurring interval in days, weeks, months, or even years. To do this, use on of the APP_Order constants to define the type of interval. For instance:

// Setting a recurring period requires an interval and interval type
$order->set_recurring_period( $period, $period_type );
 
// Settings approx 90 days using days, weeks, or months
$order->set_recurring_period( 90, APP_ORDER:RECUR_PERIOD_TYPE_DAYS );
$order->set_recurring_period( 12,  APP_ORDER:RECUR_PERIOD_TYPE_WEEKS );
$order->set_recurring_period( 3, APP_ORDER:RECUR_PERIOD_TYPE_MONTHS );
 
// You can even set times in years
$order->set_recurring_period( 5,  APP_ORDER:RECUR_PERIOD_TYPE_YEARS );

Note that there are limitations on this based on the payment processor being used. For instance, PayPal only allows recurring periods of 1-90 days, 1-52 weeks, 1-24 months, or 1-5 years.

You can also find out about an already recurring order by using the following methods:

$order->get_recurring_period();
$order->get_recurring_period_type();
 
$order->is_recurring(); // Return true if a recurring period is set

Processing Recurring Orders

Recurring orders are processed very similarly to regular instant orders. The first order being processed (where set_recurring_period is called on), is sent through the regular process() method of a gateway.

After the gateway complete()s this first order, Payments automatically detects the recurring period and creates a new order scheduled in the future for the correct date. Later on, a cron job detects when an order is ready to be processed and then sends that order to the process_recurring() method of the gateway.

class My_Recurring_Order implements APP_Payment_Processor, APP_Recurring_Payment_Processor {
 
    public function process( APP_Instant_Order $order, array $options ) {
        // order process regularly the first time
    }
 
    public function process_recurring( APP_Instant_Order $order, array $options ) {
        // future orders are processed using process_recurring
    }
 
}

In process_recurring(), gateways are ran automatically. This means unlike the regular process() method, users will not be available to give input. If a gateway is able to successfully charge or verify that a customer has paid for the new order, the gateway will use the complete() method to complete the order. After that point the order will move on to be activated and so on just like a regular order.

If a gateway cannot verify/charge the customer for the order, the order system will automatically reprocess the order by sending it through process_recurring() periodically. However, orders that are not able to be completed over time will be given a lower priority than orders whose scheduled payment date has just recently passed.

If a gateway deems an order as un-processable, the gateway can make it as failed() and it will no longer attempt to be processed.