-
Notifications
You must be signed in to change notification settings - Fork 38
Recurring Contribution Job
By default, when you install the iATS extension, a daily recurring system job is enabled that takes care of triggering recurring contributions. If you don't have any recurring contributions, you can disable it, but it won't hurt to leave it on either.
If you do have recurring contributions, and wish to use some of the advanced features as noted here https://civicrm.org/blogs/adixon/recurring-payments-advanced-functions, read on.
To do this, you'll need access to your system cron. First, disable the default system job "iATS Payments Recurring Contributions (Daily)" via your web interface. That one generally will run on the first available opportunity each day and trigger all the recurring jobs of that day (even if the time is marked later that same day).
Instead run a cron that only triggers this job, at the specific time you'd like. With Drupal, you could use a line like this in your crontab:
0 6 * * * /usr/bin/php /usr/local/bin/drush/drush.php --root='<your document root>' --uri='<your website base url>' -u 1 cvapi job.iatsrecurringcontributions
But wait ...
If you use the fixed schedules feature of the iATS extension (i.e. restricting recurring contributions to only the 22nd of the month, for example), you don't need to run your crontab every day. Normally, the fixed schedule functionality will mean that on other days no recurring contributions will be triggered, but you might was well be sure and not have to worry, using, for example, this kind of crontab entry:
0 6 22 * * /usr/bin/php /usr/local/bin/drush/drush.php --root='<your document root>' --uri='<your website base url>' -u 1 cvapi job.iatsrecurringcontributions
Or if you were using more than one day, e.g. the 7th and the 22nd:
0 6 7,22 * * /usr/bin/php /usr/local/bin/drush/drush.php --root='<your document root>' --uri='<your website base url>' -u 1 cvapi job.iatsrecurringcontributions
By default, the extension will retry non-critical failed contributions three times before advancing the next scheduled contribution date. So if you're using the fixed schedule and using a crontab like the above, you'll also want to add some crontab entries to try and catch up with the ones that don't go through on the assigned day. But you also may want those to show the original, intended contribution date of when it was supposed to go through, so you don't mess up your schedule and lose a month's contribution from these. To support that option, there's a switch called "catchup", which sets the receive date of the contribution to when it was supposed to go through (i.e. the value of the field called "next_sched_contribution_date"), and also calculates the new next scheduled contribution date from this back-dated receive date. Here's what that might like, running a catchup job two days after the initial one.
0 6 9,24 * * /usr/bin/php /usr/local/bin/drush/drush.php --root='<your document root>' --uri='<your website base url>' -u 1 cvapi job.iatsrecurringcontributions catchup=1
Note that on it's own, this might pick up a few contributions from cards that failed for reasons like being over limit that might get fixed on their own. But it'll be more valuable if you also schedule in some staff time to follow up with contributor cards that have failed. The failures will leave behind failed contribution records that record the message from iATS Payments.
If you use the fixed schedule,then the day of the month of that schedule will get put into the cycle_day field of the recurring contribution record. It's redundant piece of information, but useful if you want to distinguish your catch-up runs from your on-time runs, using a parameter like "cycle_day=22"
That cycle day is also handy when generating reports.
By default, the recurring contribution job will make the recurring contribution a membership payment of the same membership that the 'original' contribution was. If you don't want this, use the "ignoremembership=1" option.
To avoid running recurring contributions that haven't run for a long time unexpectedly, i.e. if their next scheduled recurring contribution is far in the past, there's a configurable setting called stale_limit, defaulting to 7 (days). If you expect to run schedules that might be staler than that, you can modify it via the job ui.
To avoid triggering a mass of recurring errors by mistake (e.g. a mistaken restore of data from several months previous ...), you can add failsafe_limit=n to the configuration of the job. By default, this feature is not enabled (same behaviour if you set it to 0). If you set it to 10 for example, then if you have more than 10 stale schedules about to generate payments, it'll abort the whole job before running any of them.