by Fabian Schuttenberg (schuttenberg (at) systopia.de)
Connection between Mandates and (recurring) Contributions
For One-Off payments, the contribution, the mandate and the debtor contact constitute the full direct debit data set. For recurring payments it is the recurring contribution, the mandate, and the debtor contact. In this case, all the individual contributions are connected to the debtor contact as well as the recurring contribution. Note that the single contributions are not directly connected to the mandate, but indirectly via the recurring contributions. In the UI however, you will also be able to see the mandate information if you click on a single contribution.
In CiviSEPA there are the following steps that need to be done in order to perform a direct debit payment and mark the payments as received. The workflow is slightly different for one-off and recurring payments. Be aware that the pre-notification is not included in the workflow-charts as currently hardly anybody is using it.
Create a Mandate
Send out Pre-Notification (optional)
Batch/generate Payments into groups
Close groups, submit XML-File to Bank
Mark payments or group of payments ans received
For One-Off payments, the workflow in CiviCRM is straight forward. By creating a mandate the corresponding contribution is automatically created for the debtor (status: pending: pay later; payment type SEPA DD ooff). After batching, sending the SEPA-file to the bank, and marking the payments as received, the contribution as well as the mandate are set to completed.
For recurring payments creating a mandate triggers the creation of a recurring contribution for the debtor. When batching for the first time, a new contribution is automatically created for the debtor (status: pending: pay later; payment type SEPA DD first). After sending the SEPA-file to the bank and marking the payments as received, the contribution is set to completed. When batching for the second time a new contribution is automatically created for the debtor (status: pending: pay later; payment type SEPA DD recur.)
As mandates are the base for any DD payments it all starts with creating a mandate. A mandate is connected to a CiviCRM Contact which is also the debtor (the person that you will receive money from). You can create a mandate for a single contact from the contact action menu which will present you with a mask (see below)
Enter all relevant data (more below) and you are good to go (except if you still need to do the pre-notification).
After you created a mandate you generate a PDF-pre-notification. You can adapt the message template to your organisation's need. However, note that you need to manually generate the pre-notification for each contact individually. Also be aware that if you take the regulations super-serious you need to send it out to your contact via postal mail and they would have to sign it and send it back to you. Not only will you probably loose many donors (who are to lazy to do that) but also you will have to set the SEPA-mandate to inactive until you have the signed form back so you do not perform any DD accidentally.
That being said, at least in Germany hardly anybody does that, also due to the fact that there is a somewhat half-hearted regulation that says you do not have do that (probably).
On the dashboard (civicrm/sepa) gives you an overview on all the groups you have, and you can trigger the batching process individually for one-off and recurring payments. As a result, CiviSEPA will create one group for each payment type per due date: one-off, recurring (first) and recurring (recurring) – provided there are valid mandates to be collected.
You can define, for how many days in advance groups shall be created. Note that if you have recurring payments that cannot be collected anymore because you missed the submission deadline, they will be marked and even deleted after a grace period. For one-off payments, the batching works slightly different. Here the batching mechanisms looks up all one-off payments that have not been submitted to the bank and puts them in a group with the next possible due date (all the parameters can be defined).
The batching mechanism was implemented like that in order to facilitate the collection of one-off payments. All other approaches would be very complicated, particularly if you submit the files manually to the bank. Note however, that in some countries that may imply bending the SEPA-Rules since officially you have to tell you debtor the exact day of the DD before collecting the money. For recurring payments this rule-bending is not advisable as there should be a fixed cycle day (e.g. money is collected every month on the 15th).
You can batch and update the payments as often as you want until you close a group. After closing a group it cannot be changed anymore. There might even be more than one group per payment type and due date: If you forgot a payment in your already submitted group, but you haven't missed the deadline yet, you can just create the missing mandate, hit the batching button again, and an additional group will be created. This is no problem as you can submit more than one Sepa-File to your bank per due date and type.
After you closed a group you can download a SEPA-File. If there is no automatic transmission of SEPA-Files to your bank yet, you will have to download files from CiviCRM and submit it to your bank manually (so far no automatic transmission has been implemented yet – this is a future feature that would need to be implemented for each bank or banking software individually).
Submitting can be done via browser (when logged in to your online-banking website). Alternatively you can also use any banking software that is able to interpret SEPA-XML-files.
As one file may only contain payments of one SEPA-payment type you will have to submit up to three individual XML-files per Due-Date!
It is important that you submit the file immediately after downloading it in order to not miss the submission deadline. In case you close a group but not submit the file in time there is no easy way to collect the money. Also you would have a lot of payments “in progress” in CiviCRM that will never be collected.
Closing a group also creates/updates the according contributions in CiviCRM – they will be set to “in progress”. During that time, they cannot be changed via the UI. At some point you will receive the money for each payment group from your bank. In order to mark all payments and the group as received the easiest way is to select the corresponding group and hit the button “received” this will set all contributions' status' in the group to “completed” and mark the group as received. Note that if you have any failed or cancelled payments you will have to find the corresponding contributions and edit them manually.
You can also use the extension CiviBanking to identify match and update each contribution individually but that will not be covered here
The dashboard (civicrm/sepa) enables you to trigger batching of One-Off and/or recurring payments. After closing a payment group you can also download the XML-Files from here. The background colour indicates how urgent it is to close the group and submit the files to the bank before the deadline will be reached and you cannot collect the money anymore.
A button enables you to switch between open and closed groups. Closed groups can be marked as “received”, the SEPA-file can be downloaded again if needed.
As described above, here you can enter all relevant data for the mandate and some information for the contributions that will be created by it. If the selected contact has had a mandate before, the IBAN and BIC will be pre-filed and can be selected from the drop-down menu. “Cycle day” refers to the day of the month on which the payment(s) will be made (e.g. enter 15 to do the DD each month on the 15th). In the field “Interval” enter the number of month between collection (e.g. 1 for monthly collection or 12 for yearly collection). You can set an end date for the mandate but you don't have to.
If you view a contribution that has been created by a SEPA-mandate the View is enhanced by relevant information on the connected mandate.
In an extended contribution view, if you hit „Mandate Options” you will be presented with an interface that let's you edit a mandate in certain ways.
Deleting a mandate is only possible before you created a contribution with it, batched it and closed the according group.
Set end date enables you to define when the mandate is going to end (when the last collection is supposed to be made).
According to SEPA-Guidelines you are not allowed to change a mandate so there is only the option “replace”. If you hit that button you will be presented with the create mandate mask that is pre-filled with all the information from the old mandate. As soon as you create the new mandate, it's start date will be set as the end date of the old mandate, so there will be a seamless transition between the two.
“Clone” lets you create a new mandate and the basis of an existing one. The mask will then be pre-filled with all the information of the old mandate.
PDF prenotification creates a PDF that you can print and send to your debtor via postal mail. You should adapt the template for your organization.
On the settings page (accessible via the "SEPA settings" entry in the Administration Console, or directly via civicrm/admin/setting/sepa) you can define the batching settings:
OOFF horizon: Defines the number of days into the future until which OOFF-DD should be considered when batching. E.g. 30 means OOFF-groups will be created for due dates up to 30 days from the current day on.
OOFF Notice days: Defines the minimum days into the future from which on OOFF-DD should be considered when batching. E.g. 6 means OOFF-groups will be created for due dates at least 6 days in the future. Note that this number should not be lower than the number of target days that you bank must receive the XML-File before the due date.
RCUR horizon: Defines the number of days into the future until which RCUR-DD should be considered when batching. E.g. 30 means RCUR-groups will be created for due dates up to 30 days from the current day on.
RCUR grace period: Defines the number of days for which groups that have not been submitted in time will be kept before they get deleted.
RCUR Notice days: Defines the minimum days into the future from which on RCUR-DD should be considered when batching. E.g. 6 means RCUR-groups will be created for due dates at least 6 days in the future. Note that this number should not be lower than the number of target days that you bank must receive the XML-File before the due date.
FRST Notice days: Defines the minimum days into the future from which on FRST-DD should be considered when batching. E.g. 6 means FRST-groups will be created for due dates at least 6 days in the future. Note that this number should not be lower than the number of target days that you bank must receive the XML-File before the due date.
If you click on “add” you can create an (additional) creditor and define custom batching settings for this creditor if you like.