Documentation

docs/discussion/membership.md

@@ -0,0 +1,41 @@
+# Membership Dates
+
+In a simple world, someone fills in a membership form, pays by credit card and
+their membership is active immediately.
+
+In the direct debit world, things happen on different dates:
+
+1. `setup_date` - fill in a membership form, complete a direct debit mandate
+   - Recurring Contribution created with status In Progress  
+     `start_date = charge_date`
+   - Contribution created with status Pending  
+     `receive_date = charge_date`
+   - Membership created with status Pending  
+     `join_date`, `start_date`, `end_date` are blank
+
+2. `charge_date` - first payment charged (4-5 working days later)
+
+3. `webhook_date` - GoCardless fires webhook (one working day after the `charge_date`)
+
+   - Contribution updated to status Completed
+
+   - Membership updated to status New  
+     `join_date = start_date = webhook_date`  
+     `end_date = start_date + membership_length`
+
+This appears to be identical date behaviour to creating a membership with a
+pending cheque payment and then later recording the cheque as being received.
+The membership will start when the payment is recorded and the contribution
+status set to Completed. The end date is recalculated to be a year (or other
+membership length) from the start date so that members get a full year of
+benefit.
+
+However... some might want the membership to start as soon as the mandate is
+set up, before waiting for the first payment. The current date logic is handled
+by core so this extension would need to override that in a couple of places to
+implement a different scheme.  Since that is not specific to this payment
+processor, it might be better to do this as an enhancement to core, or a
+separate extension.
+
+See also: [How to set up for membership](/howto/membership.md)
+

docs/howto/alternative-installs.md

@@ -0,0 +1,41 @@
+# Alternative install instructions
+
+As well as installing in-app, you can install from the releases page, or
+developers might like to install from `git clone`.
+
+The packaged version of this extension include the GoCardlessPro PHP libraries
+and exclude some dev-only bits including the `bin`, `cli` and `tests`
+directories.
+
+## Installing from release archive
+
+The [releases
+page](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/releases)
+lists all the releases; you normally want the latest one.
+
+**Be sure to download the .tgz or .zip file with the full name of the
+extension in it, not the source code**
+
+Unzip that in your extensions directory, then install.
+
+## Installing from git clone
+
+This extension requires the GoCardlessPro PHP library. Here's how to install
+from the \*nix command line. You need
+[composer](https://getcomposer.org/download/).
+
+    $ cd /path/to/your/extensions/dir
+    $ git clone https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless.git
+    $ cd uk.artfulrobot.civicrm.gocardless
+    $ composer install
+    $ cv en gocardless # assuming you have cv installed.
+
+That should then bring in the GoCardlessPro dependency and you should be good to
+go.
+
+!!! note "Worth a mention"
+    Side note: pre 1.9.3, this extension bundled a version of the Guzzle
+    library. Since this is already included in CiviCRM (and has been for
+    a while) it is now no longer included.
+
+

docs/howto/membership.md

@@ -0,0 +1,18 @@
+# Setting up for membership
+
+The "Auto-renew" option is required for the GoCardless payment processor to
+handle memberships.
+
+If you use Price Sets and you have the "Auto renew option, not required"
+selected then the user will not be shown the tick-box allowing them to select
+Auto Renew, and this will break things. So better to use the straight forward
+auto renew option rather than give an option that will break things.
+
+Technical people might like to know that without this, CiviCRM creates a single
+contribution and a membership record, but no `contribution_recur` record. This
+causes a crash completing the redirect flow because it can't figure out the
+interval (i.e. 1/year or such). It is possible to look that up from the
+membership ID however that leads to the situation described above, and it's then
+not clear what happens when the next payment comes in as it will not match up
+with a `contribution_recur` record.
+

docs/howto/prefill.md

@@ -0,0 +1,18 @@
+# Pre-filling fields on the GoCardless hosted page
+
+GoCardless can pre-populate some of the fields (address, phone, email).
+This is useful in the cases when you have asked the user for this
+information as part of the form you set up in CiviCRM because it saves
+them from having to enter it twice.
+
+To use this feature just add the relevant fields to a CiviCRM Profile that you
+are including in your contribution (etc) page.
+
+Addresses, emails, phones all take a location type (Primary, Billing, Home,
+Work...). If you have used more than one location type this plugin needs to
+choose which to send to GoCardless. It picks fields using the following order of
+preference:
+
+1. Billing
+2. Primary
+3. anything

docs/reference/changes.md

@@ -0,0 +1,146 @@
+# Change log
+
+## 1.9.3
+
+- Reduce timeout for changing "Pending" recurring contributions to "Failed" from 24 hours to 0.66 hours. See [issue #76](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/issues/76) You can still override this as a parameter, should you wish.
+
+- developers: fixed problem getting and setting the processor ID in import script. Thanks @jmdh for this. Also, there's been a massive refactor of the import script.
+
+- Use `supplemental_address_1` and 2 when prefilling GC address fields. Thanks @TomCranshaw
+
+- Implement new doCancelRecurring and support payment propertyBag, needed in recent core versions. Thanks @mattwire
+
+- Exclude guzzle dependency of the GoCardless library: CiviCRM core already provides guzzle 6, so this extension bringing it in as well is not needed or helpful.
+
+- New docs!
+
+## 1.9.2
+
+- Move to `Payment.create` API instead of older (and deprecated) `Contribution.completetransaction` API.
+   - This is from PR #70 (Thanks @mattwire) which fixes [issue #63](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/issues/63) on some sites where the first contribution never gets completed.
+   - Also this method is now used for repeat payments.
+
+- Fix some issues with the system checks (PR #69 thanks @mattwire)
+
+- Treat HTTP headers sent by GoCardless webhooks as case-insensitive, as now required by GoCardless (they changed the way they sent HTTP/1.1 headers).
+
+- Fix missing/invalid configuration for payment instrument and payment method.
+
+## 1.9 For CiviCRM 5.19+
+
+- **Do not install v 1.9 from civicrm.org/extensions** - it's missing the important libraries! Use 1.9.1
+
+- Supports changing the amount and cancelling a subscription via CiviCRM main user interface ([issue #6](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/issues/6)). It does not support letting supporters themselves change these things.
+
+- One-way-upgrade: we now store the GoCardless subscription ID in *both* `trxn_id` and `processor_id` in the `civicrm_contribution_recur` table. This is because some parts of CiviCRM's UI require us to reference the record via `processor_id` which was unused up to this point. An upgrade task should populate existing data.
+
+- Some membership dates logic was failing in the tests under CiviCRM 5.19. This version passes its tests again.
+
+- Fix issue when setting up a weekly membership ([issue #59](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/issues/59) - thanks to MJW Consulting for reporting and suggesting fix)
+
+- Improvements to code standards; better support for translation possibilities; move tests to phpunit6.
+
+## 1.8 Big changes
+
+- **Now with pictures** showing the lifecycle of Contribution and
+  ContributionRecur records.  
+  ![Lifecycle diagrams](/lifecycle.svg)
+
+- **Major change, possibly breaking**: multiple GoCardless payment processors
+  now allowed. Previous versions had assumed a single GoCardless payment
+  processor, and that's fine for most organisations. However, some organisations
+  have cause to use multiple GoCardless accounts with one CiviCRM instance.
+
+  **This change should hopefully be invisible to you and existing sites should
+  continue to work as before**, with the **possible exception** of anyone who
+  has done a custom (non-CiviCRM Contribution Page) donation form and used
+  the GoCardless classes directly. If you have done this then you need to
+  adjust your code, removing calls to:
+
+  1. `CRM_GoCardlessUtils::getApi`
+  2. `CRM_GoCardlessUtils::getRedirectFlow`
+  3. `CRM_GoCardlessUtils::getPaymentProcessor`
+
+  In cases (1), (2), you should now be looking to find an appropriate
+  `CRM_Core_Payment_GoCardless` payment processor object (e.g. use
+  ```php
+  // This assumes you only have one active GoCardless processor.
+  $processor_config = civicrm_api3(
+      'PaymentProcessor',
+      'getsingle',
+      ['payment_processor_type_id' => 'GoCardless',
+       'is_active' => 1, 'is_test' => 0]);
+  $processor = Civi\Payment\System::singleton()->getByProcessor($processor_config);
+  $redirect_flow = $processor->getRedirectFlow(...);
+  $gc_api = $processor->getGoCardlessApi();
+  ```
+
+  ) and call its methods
+  which have the same names. In case (3) please just use CiviCRM's native
+  methods for finding a payment processor.
+
+  Currently these methods are left in but will trigger `E_USER_DEPRECATED`
+  errors to help you find use.
+
+
+- **Now handles "Late Failures"**
+
+  With BACS (and SEPA, although that's not yet supported here) payments can
+  apparently be "Confirmed" one day, then next day they can still fail. This
+  is just to keep you on your toes.
+
+  It's called [late failure](https://support.gocardless.com/hc/en-gb/articles/360001467265-Payment-failures).
+
+  Until v1.8 we didn't know about late failures which would result in
+  'Completed' contributions being recorded which had actually failed the next
+  day.
+
+  This new version of the extension handles late failures by changing the
+  Contribution status to Refunded. Note that CiviCRM will not let us change a
+  Completed Contribution to Failed, which is why it's processed as a refund.
+
+- **Scheduled job for abandoned/failed mandate setups**
+
+  When a user clicks submit and is redirected to the offsite GoCardless page to
+  enter their bank details, a recurring contribution and a contribution record
+  are created as Pending on their Contact record.
+
+  If the user gives up at this point then those records would stay in "Pending",
+  which means you can't then easily differentiate between those abandoned ones
+  and the ones that should complete soon.
+
+  v1.8 includes a scheduled job which will look for any Pending recurring
+  contributions older than 24 hours and will mark them as Failed. The Pending
+  Contribution record is marked as Cancelled.
+
+  So you can now find abandoned set up attempts by searching for Failed
+  recurring payments.
+
+## 1.7
+
+- Fixed issue in certain use cases that resulted in the First Name field not
+ being pre-populated ([issue #45](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/issues/45)). Also further thanks to Aidan for knotty
+ discussions on membership.
+
+- Fixed issue that caused *other* payment processors' configuration forms to
+ not save. ([issue #49](https://github.com/artfulrobot/uk.artfulrobot.civicrm.gocardless/issues/49))
+
+##  1.6 "stable"!
+
+- Membership now supported thanks to work by William Mortada @wmortada and
+ Aidan Saunders @aydun, and this extension is in production use by quite a few
+ organisations so calling this release stable.
+
+- GoCardless forms are now pre-filled with address, email, phone numbers if
+ you have collected those details before passing on to GoCardless. Thanks to
+ [Vitiligo Society](https://vitiligosociety.org.uk/) for funding this work.
+
+- Updated GoCardlessPro library to 1.7.0 just to keep up-to-date.
+
+### 1.5beta
+
+Should now respect a limited number of installments. Previous
+versions will set up an open-ended subscription. You may not have wanted that
+;-) Also updated GoCardlessPro library from 1.2.0 to 1.6.0
+[GoCardlessPro changelog](https://github.com/gocardless/gocardless-pro-php/releases)
+should not have broken anything.

docs/reference/import.md

@@ -0,0 +1,9 @@
+# Developers: Importing from GoCardless
+
+If you clone from the github repo, you'll see a cli directory. This contains a
+script I used as a one-off to import some pre-existing GoCardless subscriptions.
+It's not a fully fledged tool, but it may help others with one-off import tasks
+to build a tool for their own needs from that.
+
+It can be used to import all contacts, recurring contributions and
+contributions from your GoCardless account.

docs/reference/technical.md

@@ -0,0 +1,88 @@
+# Technical notes
+
+GoCardless sends dozens of webhooks and this extension only reacts to the
+following:
+
+- payments: confirmed and failed.
+- subscriptions: cancelled and finished.
+
+The life-cycle would typically be:
+
+![Lifecycle image](/lifecycle.svg)
+
+It may be more helpful to view the image full size:
+[lifecycle.svg](/lifecycle.svg) (nb. it is created from lifecycle.dot
+using graphviz)
+
+1. User interacts with a CiviCRM Contribution form to set up regular
+   contribution. On submitting the form the user is redirected to the GoCardless
+   website after the following records are set up in CiviCRM:
+
+     - a **pending** contribution
+     - a **pending** recurring contribution
+
+   Those records have receive and start date set (by core CiviCRM) to the date
+   and time the form was submitted (as you might expect). However, once the user
+   completes the page(s) on the GoCardless website they are redirected back to
+   your website which completes the set up. On completion, the receive date of
+   the contribution and the start date of the recurring contribution will have
+   been set to a date **in the future**. This is the date provided by GoCardless
+   itself and corresponds to the earliest date they can make a charge.
+
+   Also, the recurring contribution record is now set to *In Progress*.
+
+   The completion process sets up the following at GoCardless:
+
+     - a **customer**
+     - a **mandate**
+     - a **subscription** - the ID of this begins with `SB` and is stored in the
+       CiviCRM recurring contribution `trxn_id` and `processor_id` fields
+     - a lot of scheduled **payments**
+
+
+2. GoCardless submits the charge for a payment to the customer's bank and
+   eventually (4-5 working days after creation) this is confirmed.
+   It sends a webhook for `resource_type` `payments`, action `confirmed`. At
+   this point the extension will:
+
+     - look up the payment with GoCardless to obtain its subscription ID.
+     - look up the CiviCRM recurring contribution record in CiviCRM from this
+       subscription ID (which is stored in the transaction ID field)
+     - find the pending CiviCRM contribution record that belongs to the
+       recurring contribution and update it, setting status to **Completed**,
+       setting the receive date to the **charge date** from GoCardless (n.b.
+       this is earlier than the date this payment confirmed webhook fires) and
+       setting the transaction ID to the GoCardless payment ID. It also sets
+       amount to the amount from GoCardless.
+     - check that the status on the CiviCRM recurring contribution
+       record is 'In Progress'. (It should be, but the check is there because we
+       previously did things differently.)
+
+Note: the following working day the GoCardless payment status is changed from `confirmed` to
+`paid_out`. Normally the confirmed webhook will have processed the payment
+before this happens, but the extension will allow processing of payment
+confirmed webhooks if the payment's status is `paid_out` too. This can be
+helpful if there has been a problem with the webhook and you need to replay
+some.
+
+3. A week/month/year later GoCardless sends another confirmed payment. This time:
+
+     - look up payment, get subscription ID. As before.
+     - look up recurring contribution record from subscription ID. As before.
+     - there is no 'pending' contribution now, so a new Completed one is
+       created, copying details from the recurring contribution record.
+
+4. Any failed payments work like confirmed ones but of course add or update
+   Contributions with status `Failed` instead of `Completed`.
+
+5. The Direct Debit ends with either cancelled or completed. Cancellations can
+   be that the *subscription* is cancelled, or the *mandate* is cancelled. The latter would
+   affect all subscriptions. Probably other things too, e.g. delete customer.
+   GoCardless will cancel all pending payments and inform CiviCRM via webhook.
+   GoCardless will then cancel the subscription and inform CiviCRM by webhook.
+   Each of these updates the status of the contribution (payment) or recurring
+   contribution (subscription) records.
+
+
+
+

doc/tutorial/index.md → docs/tutorial/index.md

@@ -2,11 +2,11 @@
 
 This will take you through setting up a GoCardless test account, setting
 this up in CiviCRM, and making your first test contribution. It is easy to
-set up a sanbox account and much better to do this than to use a real
+set up a sandbox account and much better to do this than to use a real
 account for testing/learning.
 
-After completing the tutorial you can pretty much follow it through again
-for a live account.
+**After completing the tutorial you can pretty much follow it through
+again for a live account.**
 
 Pages:
 
@@ -21,6 +21,7 @@ Pages:
 
 5. [Make a contribution](/tutorial/make-contribution.md)
 
+6. [Extra](/tutorial/extra.md)