[DRAFT] Merge old and new documentation

docs/configuration.md

@@ -0,0 +1,33 @@
+# Configuration (docs merge)
+
+# Step 0: Prepare before implementing CiviSEPA
+There is some general advice to consider when implementing the CiviSEPA extension for your organization // TODO: Link to?
+Also notice the Pros and Limitations in the current state //TODO link to?
+
+# Step 1: Download & Install the extension
+The CiviSEPA extension is not published in the public extension directory of CiviCRM yet. However, a stable version has been released and can be downloaded/cloned from the GitHub repository: https://github.com/Project60/org.project60.sepa/releases
+
+Put the extension into the extensions folder of your CiviCRM site (as configured under "Administer | System Settings | Directories") and install it like any extension through "Administer | Customize Data and Screens | Manage Extensions".
+
+# Step 2: Create a creditor
+A creditor represents information about the bank account that will receive the SEPA drafts. You can configure these in the "CiviSEPA Settings": `.../civicrm/admin/setting/sepa`
+
+# Step 3: Understand the SEPA workflow with CiviSEPA
+The intended workflow with the CiviSEPA extension is described here: Integration of SEPA DD in CiviCRM //TODO Link
+
+# Step 4: Adapt features with your own custom extension
+If you need customised mandate references, exclude certain collection dates, or add a custom transaction message to the collection, you want to create a sepa customization extension implementing the following hooks:
+* `civicrm_create_mandate` - to generate custom mandate reference numbers
+* `civicrm_defer_collection_date` - to avoid days when your bank won't accept collections. (Version 1.2+ can skip weekends w/o this hook)
+* `civicrm_modify_txmessage` - to customize the transaction message (Version 1.2+ can set a generic message w/o this hook)
+
+An example implementation is available on GitHub for your convenience: [org.project60.sepacustom](https://github.com/Project60/org.project60.sepa/tree/master/org.project60.sepacustom)
+# Step 5: Create Contribution Pages for SEPA
+CiviSEPA provides a payment processor that can be used in contribution pages.
+
+First, add a new CiviSEPA payment processor in the Payment Processors administration section ("Administer | System Settings | Payment Processors"). (The "Name" you set here is also used in public forms, so use something natural and generic.)
+
+You can then select this payment processor like any other payment processor for your contribution pages.
+
+# Step 6: Import existing SEPA mandates
+Is it possible to import SEPA mandates, accounts etc. that have been processed outside CiviCRM previously and should now be managed using CiviSEPA? //TODO Fabian?

docs/merge-into.md

@@ -0,0 +1,35 @@
+** (docs merge) This extension integrates SEPA (Single Euro Payments Area) into CiviCRM. It's the perfect way to 
+manage direct debit payments in the whole EURO zone without having to resort to an expensive bureau.**
+
+
+## Status
+In the course of the development the project unfortunately split into three branches, mostly due to some very tight deadlines with different requirements. Since early July 2014 there is a joint version, merging the branches of Xavier Dutoit (tttp) and Björn Endres (SYSTOPIA). Both versions have, individually, been used in production environments since the beginning of 2014.
+
+Maintainer: Björn Endres (endres (at) systopia.de) and Xavier Dutoit (xavier (at) tttp.eu)
+- Repository: https://github.com/Project60/org.project60.sepa
+- Releases: https://github.com/Project60/sepa_dd/releases
+- Planned releases: https://github.com/Project60/org.project60.sepa/milestones
+- Bugs and issues: https://github.com/Project60/org.project60.sepa/issues
+
+
+## usecases and further infos
+- **Nicely integrated with [CiviBanking](https://docs.civicrm.org/banking/en/latest/)**
+  CiviSEPA is nicely integrated with the extension [CiviBanking](https://docs.civicrm.org/banking/en/latest/) which offers a very sophisticated framework for importing bank account statements and matching the enclosed payments with contributions and contacts in CiviCRM.
+
+### Limitations
+
+- **Manual Submission of XML-Files**
+  So far no automatic transmission to a bank has been implemented. If you only do DD collections a couple of times per month, this should not be too much of a problem. However, if you want to do DD it more often and/or flexible, manual transmission may be time-consuming and some work would need to be put into automatisation.
+
+- **Pre-Notification**
+  The function for pre-notification is only designed to create a PDF-file of mandate that you can print out and send to your constituents to let them sign it. There are no further features such as sending it out via E-Mail. Also, if you use pre-notification you will have to adapt your workflow and some settings to ensure that mandates are inactive as long as you did not receive the signed version of the mandate from your constituent.
+  So far, all our users don't do formal pre-notification at all or are fine with the current basic functionality. If you have a workflow that is not covered by the current implementation, just talk to us.
+
+
+## More Information
+- CiviSEPA Setup Instructions: https://wiki.civicrm.org/confluence/display/CRM/CiviSEPA+Setup+Instructions
+- Introduction to SEPA in general: SEPA-Basics https://wiki.civicrm.org/confluence/display/CRM/SEPA-Basics
+- Integration of SEPA DD in CiviCRM https://wiki.civicrm.org/confluence/display/CRM/Integration+of+SEPA+DD+in+CiviCRM
+- Things to consider when implementing CiviSEPA https://wiki.civicrm.org/confluence/display/CRM/Things+to+consider+when+implementing+CiviSEPA
+- Technical information Page https://wiki.civicrm.org/confluence/display/CRM/CiviSEPA+Technical+Specifications
+- Use [CiviBanking](https://docs.civicrm.org/banking/en/latest/) to "close the loop"

docs/setup-instructions.md

@@ -0,0 +1,35 @@
+# CiviSEPA Setup Instructions (docs merge)
+todo remove https://wiki.civicrm.org/confluence/display/CRM/CiviSEPA+Setup+Instructions
+We'd like to share our experiences with implementing CiviSEPA for various customers. So, here's our advice:
+
+## Understand the SEPA workflow with CiviSEPA
+
+### Workflow
+The intended workflow with the CiviSEPA extension is described here: Integration of SEPA DD in CiviCRM // todo add link?
+
+Make sure that you understood your organisation's workflow and that it fits the features of CiviSEPA. 
+It is particularly important how often per month you would like to collect money and if you want to do one-off and/or recurring contributions. Complexity/work load will grow according to the number of collection days per month. This is particularly due to the target-day-approach and the fact that you have to submit the xml-files manually and on time.
+
+In case you use any banking or accounting software, make sure, it can be integrated in the new process (e.g. that the banking software can interpret SEPA-files).
+
+### Talk to your bank
+
+When planning your workflow, also make sure to talk to your bank and ask them about technical details (accepted formats), existing interfaces to upload your data and ANY exceptions or deviations from the standards that they may have.
+
+Also ask them, how received payments will show up on your bank statements (e.g. single payments or bulk) and make sure, that suits your needs.
+
+### Ensure timely submission
+
+As described above, the fixed due dates imply that you might loose money if you do not submit files on time. Make sure that files can always be submitted timely. That implies, submitting them not on the last possible day, in case there are any problems. Also make sure that more than one person is familiar with CiviSEPA and has the necessary permissions to create and submit files (in case the responsible person is absent).
+
+
+## Create Contribution Pages for SEPA
+Payment Processors are necessary if you want to https://github.com/Project60/org.project60.sepapp //TODO text fabian?
+
+
+## Import existing SEPA mandates
+todo: kurze beschreibung import nicht via oberfläche möglich. Kurze beschreibung API sepa create mandate create full
+
+
+## Run a full test-cycle
+Before going live, run a full test cycle and do a couple of real transactions in different formats (One-Off, Recurring First and Recurring recurring). After receiving them, mark the groups as received and so on. Be particularly keen if you use any additional software to upload the xml-files as they may change information such as the due date.

docs/understanding-sepa.md

@@ -0,0 +1,62 @@
+# Understanding SEPA (docs merge)
+
+We will only cover some selected and relevant aspects of SEPA as the whole matter is very complex and many much more comprehensive compendia have been written about it already. For some countries that have been using Direct Debit (DD) Payments regularly before (such as Germany), SEPA made things worse as it is more complicated than the old systems – both in regard to technical issues and the workflow of handling the payments. On top of that, is spite of a year-long process of developing a common SEPA-standard, many countries and sometimes even banks have their own exceptions or special rules.
+
+Thus CiviSEPA was build in a way to be as adaptable as possible in order to deal with all those requirements that will most likely differ from organisation to organisation.
+
+##  Involved Parties
+The following illustration depicts the general workflow of a SEPA-DD:
+
+![Screenshot](img/description-civi-sepa.png)
+
+## SEPA Payment-types
+
+You can initiate two types of SEPA Direct Debits:
+- one-off (OOFF)
+- recurring (RCUR)
+
+**One-off** is used when the debtor, via the mandate, has only allowed you to perform one single direct debit. After the first direct debit the mandate has expired and you cannot use it anymore. Recurring is used when the debtor mandate allows for regular collections. This type of collection can be split into three sub-types:
+
+**Recurring (first)**: Must be used when you initiate the first direct debit under a new mandate.
+
+**Recurring (Recurring)**: Must be used when you initiate the subsequent direct debits under the mandate
+
+
+There is also a third subtype (Recurring final) which can be used when initiating the last DD under a mandate but this is not implemented in CiviSEPA
+
+## Mandates
+For each DD you need a mandate. It specifies all relevant such as information on the debtor, the amount of the payment. etc. Each mandate must have a mandate reference which must be unique for each mandate in combination with your SEPA Direct Debit creditor identifier.
+
+## Pre-Notification
+Officially, your debtor has to sign a SEPA Direct Debit paper mandate for a particular contract held with you before you may start sending collections to the debtor. This means that you would need to print out the mandate, send it out to the debtor (e.g. your donor) who then has to sign it and send it back to you.
+
+However, there is an ongoing discussion on how to interpret this rule and you will need to find out, how your country's and/or bank's approach is toward the pre-notification (see page Integration of SEPA DD in CiviCRM).
+
+## Due Date & Target Days
+One major aspect (and headache) of SEPA is, that you have to specify a due date on which you have to collect the money. Officially, you have to inform the debtor of that due-date and collect the money on that day – not earlier and not later. This means, that if you fail to do so, you are officially not allowed to collect the money anymore.
+
+Not complicated enough? The due date must also be a “Target Day”. Target Days are those days that banks actually do DD. Saturdays and Sundays are excluded, as well as certain holidays. So if your due-date is for example a Saturday (e.g. August 16, 2014), you would have to set it to the following Monday (August 19, 2014).
+
+There are different approaches on how this is handled. In our experience after submitting the SEPA-XML-files to your bank, they will correct the Due Date automatically to the next possible target day if the due date is not a target day. Again, you will have to check with your bank on how they will handle that. Also, if you use a banking software, to upload the xml-file this software may alter the date accordingly...
+
+## Submission Deadlines
+Depending on the type of payment, there are certain deadlines for submitting the information to your bank. For the CORE-scheme (which is the standard for DD payments that are not b2b) you need to to submit the information (that is the XML-file) as follows:
+- One-Off & Recurring (First): Due Day – 5 Target Days – 1 Calendar Day (at 22:00 CET/CEST)
+- Recurring (Recurring): Due Day – 2 Target Days – 1 Calendar Day (at 22:00 CET/CEST)
+
+In a nutshell that means that for each collection the number of days you have to submit your data in advance may differ each time depending on weekends, holidays etc. For One-Off & Recurring (First) you will need to send it at least 6 days before but usually more. On an easter-weekend with 4 consecutive non-target-days it will be much more.
+
+Given the fact that for example in Germany it usually only took 1-2 days to initiate and complete a DD payment, you can imagine how happy everyone is about those deadlines. No surprise, another SEPA-scheme emerged called COR1 (shorter cut-off times) which is however not supported by all countries/banks...
+## Challenges
+The descriptions above only reflect some rough basics and are not comprehensive at all. If you really want to go into the details, google it and prepare for a trip down the rabbit hole. Here we would like to describe in what ways the SEPA-standards continue to pose challenges to implement DD in CiviSEPA.
+
+## Different Ways of submitting SEPA-Files
+Each bank has its own ways of how files can/have to be submitted to them. In addition, if you use a banking software this may also change on how the information is transmitted as the software often interprets and the payment information contained in a SEPA-File before sending it to the bank.
+
+Hence, any automatic transmission of SEPA-Files from CiviCRM to a bank must be implemented individually for each customer – or do it manually as described on the page Integration of SEPA DD in CiviCRM.
+## Fixed Due Date
+As collection needs to take place on a fixed due date and you have deadlines for submitting the xml-files to the bank, there is always a risk of messing up. If you forget to submit the data or something goes wrong, there is no proper way of collecting the money at a later point in time. There is -of course- workarounds for this case, but they are bending the rules. In addition, the complicated target-day-system makes it hard to plan, when a file has to be submitted.
+
+Especially if you submit your information to the bank manually, you need to plan your workflow and responsibilities very well or run the risk to loose payments...
+## Country-, Bank- or Software-specific rules/exceptions
+As SEPA itself is not complicated enough and each country has its own DD-History many exceptions from the rules have emerged and will continue to do so. Also each bank may interpret the SEPA-”standards” slightly differently in ways that suit them best. Finally, if you use a banking software that interprets your payment information before submitting it to the bank, be ready to to do a lot of analysing in case of problems (needless to say, that your bank and banking-software-company will blame each other or you for any mistakes/problems...)