by Fabian Schuttenberg (schuttenberg (at)

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.


CiviSEPA Workflow

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.

  1. Create a Mandate

  2. Send out Pre-Notification (optional)

  3. Batch/generate Payments into groups

  4. Close groups, submit XML-File to Bank

  5. Mark payments or group of payments ans received

Workflow One-Off

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.



Workflow Recurring

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.)


Creation of Mandates

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).

Batching and Generating Groups

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.

Downloading and submitting the XML-Files

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.

Marking payments as received

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


User Interface

Batching and group overview

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.

andate Creating


Mandate Creation

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.

Enhanced View of (Recurring) Contributions

If you view a contribution that has been created by a SEPA-mandate the View is enhanced by relevant information on the connected mandate.

Mandate Editing

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.

Batching Settings and Creditors


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:

If you click on “add” you can create an (additional) creditor and define custom batching settings for this creditor if you like.