diff --git a/docs/images/contribution_futurerecur.png b/docs/images/contribution_futurerecur.png new file mode 100644 index 0000000000000000000000000000000000000000..918e908b0f89dbfacadb0993f038fe70dd4a219a Binary files /dev/null and b/docs/images/contribution_futurerecur.png differ diff --git a/docs/images/settings_futurerecur.png b/docs/images/settings_futurerecur.png new file mode 100644 index 0000000000000000000000000000000000000000..f5a9276bf0cf519289b10a4ecb99e8e0bd8d5745 Binary files /dev/null and b/docs/images/settings_futurerecur.png differ diff --git a/docs/recur.md b/docs/recur.md index c17b34ac3409cbd0da8454d6d22ff14715fa0021..dd125a04cbb1cde4a4fee7ba403c7d257c47de3e 100644 --- a/docs/recur.md +++ b/docs/recur.md @@ -9,6 +9,16 @@ When you create a recurring contribution in CiviCRM using the Stripe payment pro !!! tip "If you are using recurring contributions make sure you have webhooks configured correctly" See [Webhooks](webhook.md) +## Starting a Recurring contribution in the future +If you would like your users to be able to specify a future recurring start date you can enable +`Enable public selection of future recurring start dates` in *Administer->CiviContribute->Stripe Settings*. + + + +Then your users will see an option to select a start date for the contribution: + + + ## Cancelling Recurring Contributions You can cancel a recurring contribution from the Stripe Dashboard or from within CiviCRM. diff --git a/docs/releasenotes.md b/docs/releasenotes.md index 8fd5b9ddd66bab60eccdead30549cd635b30fc0e..6212b3d01f7a5d0efb0f87baea11659eea242982 100644 --- a/docs/releasenotes.md +++ b/docs/releasenotes.md @@ -9,6 +9,17 @@ Where: * minor: Breaking change in some circumstances, or a new feature. Read carefully and make sure you understand the impact of the change. * incremental: A "safe" change / improvement. Should *always* be safe to upgrade. +## Release 6.5 - not yet released +**This release REQUIRES that you upgrade mjwshared to 0.9** + +* Implement [#199](https://lab.civicrm.org/extensions/stripe/-/issues/199): + * Support future recurring start date on backend forms + * Add support for selecting and creating subscriptions with future start date on frontend forms +* Fix [#221](https://lab.civicrm.org/extensions/stripe/-/issues/199) Return 200 OK for webhooks that stripe can't match to CiviCRM. Look for contribution using subscription_id for future recurring start date +* Map customer to contact ID in IPN +* Handle invoice.paid, invoice.finalized IPN events - we now create the new contribution once we receive the invoice.finalized event. It will then be transitioned to Completed by invoice.paid/invoice.payment_succeeded +* Record refund against the already recorded payment in CiviCRM so we update financial items correctly + ## Release 6.4.2 * Fix [#210](https://lab.civicrm.org/extensions/stripe/-/issues/210): If there are multiple reCaptcha on the page check and validate the one on the Stripe billing form only. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000000000000000000000000000000000000..654489b077310c11efd8dade56a132c25379c019 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,67 @@ +# Roadmap of planned features +This roadmap may not always be up to date but gives an idea of what is planned and where funding/support is required. + +## Automatic import of subscriptions / payments + +If we already have the Stripe customer in CiviCRM we can import subscriptions and one-off contributions that were +created outside of CiviCRM (eg. via WooCommerce, Stripe Dashboard). + +### Specification +1. Add a setting to control whether import should happen automatically. +2. Update Stripe IPN code to automatically create: + - A recurring contribution when an unknown Stripe subscription ID is received. + - A contribution linked to a recurring contribution when an unknown invoice ID is received. + - A contribution when an unknown charge ID is received (that does not have an associated invoice ID). + - A payment linked to a contribution via charge ID / invoice ID. + +### Estimate + +This would require funding for approximately 12 hours work. + +## UI to map customers to CiviCRM contacts + +Based on the existing `Stripe.Importcustomers` API we can build a UI in CiviCRM that allows to manually +confirm and map Stripe customer IDs to CiviCRM contacts. + +### Specification + +1. Build a UI that lists Stripe customers which do not exist in CiviCRM. +2. Provide options to: + - Confirm the auto-detected mapping. + - Manually find and map contact. + - Import all missing subscriptions/contributions for customer (up to certain date?). + +### Estimate + +This would require funding for approximately 16 hours work. + +## Stripe Connect + +See https://stripe.com/connect + +## Payment Requests (Google / Apple Pay) + +See https://lab.civicrm.org/extensions/stripe/-/issues/81 + +## Stripe ACH/EFT + +See https://civicrm.org/make-it-happen/stripe-ach-payments + +## Card on File + +Stripe supports saving cards and other payment methods. These can be retrieved, re-used and updated. +We would like to provide support for re-using saved cards in CiviCRM. + +### Specification + +1. Develop a method to deduplicate payment methods (see eg. https://github.com/stripe/stripe-payments-demo/issues/45). + Cards are duplicated by default and we need to clean this up before we can provide a UI to retrieve cards in CiviCRM. +2. Build a UI to allow for selection of cards to use for making payment. +3. Integrate card-selection UI into payment flow (so for example a form validation failure will remember the card you just entered and verified). + +### Estimate + +This would require funding for approximately 24 hours work. + + + diff --git a/docs/webhook.md b/docs/webhook.md index 26511f6aa92ecf6f983d7e0b0f5da00caa27d135..10e31dd22050be108409689c4c069dc677eb856b 100644 --- a/docs/webhook.md +++ b/docs/webhook.md @@ -1,15 +1,15 @@ # Webhooks ## Overview -If you are using recurring contributions with Stripe you **MUST** setup a webhook and check that it is working. Otherwise contributions will never be marked "Completed". +Stripe webhooks allow for CiviCRM to be notified of changes in payment status and new payments. -If you are not using recurring contributions the webhook, if available, will update contributions if they are refunded / cancelled / failed. +If the webhooks are not working CiviCRM will not be able to update the status of payments and recurring contributions. ## Configuring Webhooks -From version 5.4.1 the extension manages / creates the webhooks. A system check is run to verify if the webhooks are created and have the correct parameters. If not a *Wizard* is provided to create them for you. +The extension manages / creates the webhooks. A system check is run to verify if the webhooks are created and have the correct parameters. If not a *Wizard* is provided to create them for you. To check if webhooks are configured correctly login to your Stripe Dashboard and look at **Developers > Webhooks** - + ## Notifications Stripe notifies CiviCRM in the following circumstances: @@ -22,3 +22,19 @@ Stripe notifies CiviCRM in the following circumstances: * An invoice payment fails. * A subscription is cancelled. * A subscription is updated. + +## Unknown events + +If CiviCRM receives an event with information it cannot match with an entity in CiviCRM: + - customer ID => CiviCRM contact. + - subscription ID => CiviCRM recurring contribution. + - invoice ID / charge ID => CiviCRM contribution. + +The webhook will return `200 OK` and Stripe will assume it was handled successfully. This allows +for the Stripe account to be used with multiple clients (eg. CiviCRM, WooCommerce, Stripe Dashboard etc.) +without triggering webhook errors. + +You can enable `Enable Stripe IPN (Webhook) debugging?` in *Administer->CiviContribute->Stripe Settings* +if you would like to see these events in the CiviCRM logs. + +Also see [Automatic import of subscriptions / payments](roadmap.md#automatic-import-of-subscriptions--payments) on the roadmap if you'd like to see this improved. diff --git a/mkdocs.yml b/mkdocs.yml index d03b99eade68a502663875d0c1935d7750d3e0ef..b4ea38c553d43454038bd56359f0e3b63eea74cd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,3 +30,4 @@ nav: - Hooks: hooks.md - Testing: testing.md - Release Notes: releasenotes.md +- Roadmap: roadmap.md