Skip to content
Snippets Groups Projects
Commit 260deb03 authored by mattwire's avatar mattwire
Browse files

Add mkdocs documentation

parent 04e3198b
No related branches found
No related tags found
1 merge request!11Support Cancellation and major refactor of backend / webhook processing
Hide whitespace changes
Inline Side-by-side
README.md
+ 12
− 168
View file @ 260deb03
CiviCRM Stripe Payment Processor # CiviCRM Stripe Payment Processor
--------------------------------
## Requirements Integrates the Stripe payment processor (for Credit/Debit cards) into CiviCRM so you can use it to accept Credit / Debit card payments on your site.
* PHP 5.6+
* Jquery 1.10 (Use jquery_update module on Drupal).
* Drupal 7 / Joomla / Wordpress (latest supported release).
*Not currently tested with other CMS but it may work.*
* CiviCRM 5.0+
* Stripe API version: Tested on 2018-02-28
* Drupal webform_civicrm 7.x-4.22+ (if using webform integration)
### How to update Stripe API version * https://stripe.com/
Go to _Account Settings_ -> _API Keys_ tab -> click _Upgrade available_ button.
More info on how to change: https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api
## Configuration
All configuration is in the standard Payment Processors settings area in CiviCRM admin.
You will enter your "Publishable" & "Secret" key given by stripe.com.
## Installation (Web UI)
This extension has not yet been published for installation via the web UI.
## Installation (CLI, Zip)
Sysadmins and developers may download the `.zip` file for this extension and
install it with the command-line tool [cv](https://github.com/civicrm/cv).
Latest releases can be found here: https://civicrm.org/extensions/stripe-payment-processor Latest releases can be found here: https://civicrm.org/extensions/stripe-payment-processor
## Documentation
Please see: https://docs.civicrm.org/stripe/en/latest
## Installation (CLI, Git) ## Configuration
All configuration is in the standard Payment Processors settings area in CiviCRM admin.
Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git) repo for this extension and You will enter your "Publishable" & "Secret" key given by stripe.com.
install it with the command-line tool [cv](https://github.com/civicrm/cv).
```bash
git clone https://lab.civicrm.org/extensions/stripe.git
cv en stripe
```
## Webhook and Recurring Contributions
Stripe can notify CiviCRM every time a recurring contribution is processed.
In order to take advantage of this feature, you must configure Stripe with the right "Webhook Endpoint".
You can find the location of this setting in your Stripe Dashboard by clicking the API menu item on the left, and then choose the Webhook tab.
Then click Add Endpoint.
Now, you need to figure out what your end point is.
To figure out the "URL to be called" value, you need to check what ID is assigned to your payment processor.
To determine the correct setting, go back to your CiviCRM screen and click `Administer -> System Settings -> Payment Processor`
Click Edit next to the payment processor you are setting up.
Then, check the Address bar. You should see something like the following:
https://example.com/civicrm/admin/paymentProcessor?action=update&id=3&reset=1
The end of the address contains id=3. That means that this Payment Processor id is 3.
Therefore the call back address for your site will be:
civicrm/payment/ipn/3
See below for the full address to add to the endpoint (replace NN with your actual ID number):
* For Drupal: https://example.com/civicrm/payment/ipn/NN
* For Joomla: https://example.com/?option=com_civicrm&task=civicrm/payment/ipn/NN
* For Wordpress: https://example.com/?page=CiviCRM&q=civicrm/payment/ipn/NN
Typically, you only need to configure the end point to send live transactions and you want it to send all events.
### Cancelling Recurring Contributions
You can cancel a recurring contribution from the Stripe.com dashboard. Go to Customers and then to the specific customer.
Inside the customer you will see a Subscriptions section. Click Cancel on the subscription you want to cancel.
Stripe.com will cancel the subscription and will send a webhook to your site (if you have set the webhook options correctly).
Then the stripe_civicrm extension will process the webhook and cancel the Civi recurring contribution.
## API
This extension comes with several APIs to help you troubleshoot problems. These can be run via /civicrm/api or via drush if you are using Drupal (drush cvapi Stripe.XXX).
The api commands are:
* `Listevents`: Events are the notifications that Stripe sends to the Webhook. Listevents will list all notifications that have been sent. You can further restrict them with the following parameters:
* `ppid` - Use the given Payment Processor ID. By default, uses the saved, live Stripe payment processor and throws an error if there is more than one.
* `type` - Limit to the given Stripe events type. By default, show invoice.payment_succeeded. Change to 'all' to show all.
* `output` - What information to show. Defaults to 'brief' which provides a summary. Alternatively use raw to get the raw JSON returned by Stripe.
* `limit` - Limit number of results returned (100 is max, 10 is default).
* `starting_after` - Only return results after this event id. This can be used for paging purposes - if you want to retreive more than 100 results.
* `Populatelog`: If you are running a version of CiviCRM that supports the SystemLog - then this API call will populate your SystemLog with all of your past Stripe Events. You can safely re-run and not create duplicates. With a populated SystemLog - you can selectively replay events that may have caused errors the first time or otherwise not been properly recorded. Parameters:
* `ppid` - Use the given Payment Processor ID. By default, uses the saved, live Stripe payment processor and throws an error if there is more than one.
* `Ipn`: Replay a given Stripe Event. Parameters. This will always fetch the chosen Event from Stripe before replaying.
* `id` - The id from the SystemLog of the event to replay.
* `evtid` - The Event ID as provided by Stripe.
* `ppid` - Use the given Payment Processor ID. By default, uses the saved, live Stripe payment processor and throws an error if there is more than one.
* `noreceipt` - Set to 1 if you want to suppress the generation of receipts or set to 0 or leave out to send receipts normally.
# TESTING
### PHPUnit
This extension comes with two PHP Unit tests:
* Ipn - This unit test ensures that a recurring contribution is properly updated after the event is received from Stripe and that it is properly canceled when cancelled via Stripe.
* Direct - This unit test ensures that a direct payment to Stripe is properly recorded in the database.
Tests can be run most easily via an installation made through CiviCRM Buildkit (https://github.com/civicrm/civicrm-buildkit) by changing into the extension directory and running:
phpunit4 tests/phpunit/CRM/Stripe/IpnTest.php
phpunit4 tests/phpunit/CRM/Stripe/DirectTest.php
### Katalon Tests
See the test/katalon folder for instructions on running full web-browser based automation tests.
Expects a drupal (demo) site installed at http://localhost:8001
1. Login: No expected result, just logs into a Drupal CMS.
1. Enable Stripe Extension: Two payment processors are created, can be done manually but processor labels must match or subsequent tests will fail.
1. Offline Contribution, default PP: A contribution is created for Arlyne Adams with default PP.
1. Offline Contribution, alternate PP: A contribution is created for Arlyne Adams with alternate PP.
1. Offline Membership, default PP: A membership/contribution is created for Arlyne Adams with default PP.
1. Offline Membership, alternate PP: A membership/contribution is created for Arlyne Adams with alternate PP.
1. Offline Event Registration, default PP: A participant record/contribution is created for Arlyne Adams with default PP.
1. Offline Event Registration, alternate PP: A participant record/contribution is created for Arlyne Adams with alternate PP.
1. Online Contribution Stripe Default Only: A new contribution record is created.
1. Online Contribution Page 2xStripe, Test proc, use Stripe Alt: A new contribution record is created. **FAIL:
Error Oops! Looks like there was an error. Payment Response:
Type: invalid_request_error
Code: resource_missing
Message: No such token: Stripe Token**
1. Online Contribution Page Stripe Default, Pay Later: A new contribution record is created.
1. Test Webform: A new contribution is created. *Partial test only*
ONLINE contribution, event registration tests
### Manual Tests
1. Test webform submission with payment and user-select, single processor.
1. TODO: Are we testing offline contribution with single/multi-processor properly when stripe is/is not default with katalon tests?
1. Test online contribution page on Wordpress.
1. Test online contribution page on Joomla.
1. Test online event registration.
1. Test online event registration (cart checkout).
#### Drupal Webform Tests
TODO: Add these as Katalon tests.
1. Webform with single payment processor (Stripe) - Amount = 0.
1. Webform with single payment processor (Stripe) - Amount > 0.
1. Webform with multiple payment processor (Stripe selected) - Amount = 0.
1. Webform with multiple payment processor (Stripe selected) - Amount > 0.
1. Webform with multiple payment processor (Pay Later selected) - Amount = 0.
1. Webform with multiple payment processor (Pay Later selected) - Amount > 0.
1. Webform with multiple payment processor (Non-stripe processor selected) - Amount = 0.
1. Webform with multiple payment processor (Non-stripe processor selected) - Amount > 0.
## Credits
### Original Author
Joshua Walker - http://drastikbydesign.com - https://drupal.org/user/433663
### Other Credits
-------------
Peter Hartmann - https://blog.hartmanncomputer.com
For bug fixes, new features, and documentation, thanks to: ## Installation
rgburton, Swingline0, BorislavZlatanov, agh1, jmcclelland, mattwire There are no special installation requirements.
The extension will show up in the extensions browser for automated installation.
Otherwise, download and install as you would for any other CiviCRM extension.
docs/api.md 0 → 100644
+ 23
− 0
View file @ 260deb03
# API
This extension comes with several APIs to help you troubleshoot problems. These can be run via /civicrm/api or via drush if you are using Drupal (drush cvapi Stripe.XXX).
The api commands are:
* `Listevents`: Events are the notifications that Stripe sends to the Webhook. Listevents will list all notifications that have been sent. You can further restrict them with the following parameters:
* `ppid` - Use the given Payment Processor ID. By default, uses the saved, live Stripe payment processor and throws an error if there is more than one.
* `type` - Limit to the given Stripe events type. By default, show invoice.payment_succeeded. Change to 'all' to show all.
* `output` - What information to show. Defaults to 'brief' which provides a summary. Alternatively use raw to get the raw JSON returned by Stripe.
* `limit` - Limit number of results returned (100 is max, 10 is default).
* `starting_after` - Only return results after this event id. This can be used for paging purposes - if you want to retreive more than 100 results.
* `Populatelog`: If you are running a version of CiviCRM that supports the SystemLog - then this API call will populate your SystemLog with all of your past Stripe Events. You can safely re-run and not create duplicates. With a populated SystemLog - you can selectively replay events that may have caused errors the first time or otherwise not been properly recorded. Parameters:
* `ppid` - Use the given Payment Processor ID. By default, uses the saved, live Stripe payment processor and throws an error if there is more than one.
* `Ipn`: Replay a given Stripe Event. Parameters. This will always fetch the chosen Event from Stripe before replaying.
* `id` - The id from the SystemLog of the event to replay.
* `evtid` - The Event ID as provided by Stripe.
* `ppid` - Use the given Payment Processor ID. By default, uses the saved, live Stripe payment processor and throws an error if there is more than one.
* `noreceipt` - Set to 1 if you want to suppress the generation of receipts or set to 0 or leave out to send receipts normally.
### Additionally for upgrading:
* `StripeCustomer.updatecontactids` - Used to migrate civicrm_stripe_customer table to match on contact_id instead of email address.
* `StripeSubscription.updatetransactionids` - Used to migrate civicrm_stripe_subscriptions to use recurring contributions directly.
\ No newline at end of file
docs/hooks.md 0 → 100644
+ 12
− 0
View file @ 260deb03
# Hooks
In release 5.2 we introduce a framework for hooks, in a similar way to the org.civicrm.smartdebit extension.
In order to support other extensions that manipulate amounts etc we need to add additional hooks and call existing ones in more places.
Currently only a single hook is implemented, and is only called in one place.
#### hook_civicrm_smartdebit_updateRecurringContribution(&$recurContributionParams)
This hook allows modifying recurring contribution parameters during update.
* @param array $recurContributionParams Recurring contribution params (ContributionRecur.create API parameters).
docs/index.md 0 → 100644
+ 28
− 0
View file @ 260deb03
#Stripe Payment Processor for CiviCRM.
Integrates the Stripe payment processor (for Credit/Debit cards) into CiviCRM so you can use it to accept Credit / Debit card payments on your site.
* https://stripe.com/
Latest releases can be found here: https://civicrm.org/extensions/stripe-payment-processor
View this extension in the [Extension Directory](https://civicrm.org/extensions/stripe-payment-processor).
## Compatibility / Requirements
* CiviCRM 5.3+
* PHP 5.6+
* Jquery 1.10 (Use jquery_update module on Drupal).
* Drupal 7 / Joomla / Wordpress (latest supported release). *Not currently tested with other CMS but it may work.*
* Stripe API version: 2018-11-08
* Drupal webform_civicrm 7.x-4.22+ (if using webform integration)
## Credits
Current Maintainer: Matthew Wire - https://www.mjwconsult.co.uk
### Original Author
Joshua Walker - http://drastikbydesign.com - https://drupal.org/user/433663
### Other Credits
Peter Hartmann - https://blog.hartmanncomputer.com
For bug fixes, new features, and documentation, thanks to:
rgburton, Swingline0, BorislavZlatanov, agh1, jmcclelland, mattwire
docs/install.md 0 → 100644
+ 18
− 0
View file @ 260deb03
# Install / Configuration
Please do help improve this documentation by submitting a PR or contacting me.
## Configuration
All configuration is in the standard Payment Processors settings area in CiviCRM admin.
You will enter your "Publishable" & "Secret" key given by stripe.com.
## Installation
There are no special installation requirements.
The extension will show up in the extensions browser for automated installation.
Otherwise, download and install as you would for any other CiviCRM extension.
### How to update Stripe API version
More info on how to change: https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api
Go to _Account Settings_ -> _API Keys_ tab -> click _Upgrade available_ button.
Don't forget to update the webhook API version as well.
docs/recur.md 0 → 100644
+ 56
− 0
View file @ 260deb03
# Recurring Contributions and 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".
If you are not using recurring contributions the webhook is not required.
## Details
Stripe notifies CiviCRM every time a recurring contribution is processed / updated / cancelled.
In order to take advantage of this feature, you must configure Stripe with the right "Webhook Endpoint".
You can find the location of this setting in your Stripe Dashboard by clicking the API menu item on the left, and then choose the Webhook tab.
Then click Add Endpoint.
Now, you need to figure out what your end point is.
To figure out the "URL to be called" value, you need to check what ID is assigned to your payment processor.
To determine the correct setting, go back to your CiviCRM screen and click `Administer -> System Settings -> Payment Processor`
Click Edit next to the payment processor you are setting up.
Then, check the Address bar. You should see something like the following:
https://example.com/civicrm/admin/paymentProcessor?action=update&id=3&reset=1
The end of the address contains id=3. That means that this Payment Processor id is 3.
Therefore the call back address for your site will be:
civicrm/payment/ipn/3
See below for the full address to add to the endpoint (replace NN with your actual ID number):
* For Drupal: https://example.com/civicrm/payment/ipn/NN
* For Joomla: https://example.com/?option=com_civicrm&task=civicrm/payment/ipn/NN
* For Wordpress: https://example.com/?page=CiviCRM&q=civicrm/payment/ipn/NN
Typically, you only need to configure the end point to send live transactions and you want it to send all events.
Also, make sure you set the API version for the end point to 2018-11-08.
## Cancelling Recurring Contributions
You can cancel a recurring contribution from the Stripe.com dashboard or from within CiviCRM.
#### In Stripe
1. Go to Customers and then to the specific customer.
1. Inside the customer you will see a Subscriptions section.
1. Click Cancel on the subscription you want to cancel.
1. Stripe.com will cancel the subscription, send a webhook to your site and the recurring contribution will be marked as "Cancelled" in CiviCRM.
#### In CiviCRM
1. Click the "Cancel" link next to the recurring contribution.
1. Select the option to "Send cancellation request to Stripe ?" and click Cancel.
1. Stripe.com will cancel the subscription, send a webhook to your site and the recurring contribution will be marked as "Cancelled" in CiviCRM.
docs/release/release_notes.md 0 → 100644
+ 43
− 0
View file @ 260deb03
## Release 5.2
*This release introduces a number of new features, standardises the behaviour of recurring contributions/memberships to match standard CiviCRM functionality and does a major cleanup of the backend code to improve stability and allow for new features.*
### Highlights:
* Support Cancel Subscription from CiviCRM and from Stripe.
### Breaking changes:
* The extension now uses the standard CiviCRM Contribution.completetransaction and Contribution.repeattransaction API to handle creation/update of recurring contributions. This means that automatic membership renewal etc. is handled in the standard CiviCRM way instead of using custom code in the Stripe extension. The behaviour *should* be the same but some edge-cases may be fixed while others may appear. Any bugs in this area will now need to be fixed in CiviCRM core - if you want to help with that see https://github.com/civicrm/civicrm-core/pull/11556.
* When recurring contributions were updated by Stripe, they were marked cancelled and a new one created in CiviCRM. This was non-standard behaviour and causes issues with CiviCRM core functionality for membership renewal etc. This has now been changed so only one recurring contribution per subscription will ever exist, which will be updated as necessary during it's lifecycle.
* Different payment amounts are now supported for each contribution in a recurring contribution. Previously they were explicitly rejected by the extension.
### Changes:
* Add http response codes for webhook (invalid parameters now returns 400 Bad Request).
* Major refactor of webhook / events handling (fixes multiple issues, now tested and working on Joomla / Wordpress / Drupal 7).
* Update to latest version of stripe-php library.
* Handle "Customer Deleted" from Stripe.
* Drop use of civicrm_stripe_plans table and just query Stripe each time. This prevents errors when they get out of sync
### Upgrading
**You should upgrade directly from 5.0.**
Make sure you run the extension upgrades immediately after updating the code. There are two MAJOR upgrade steps:
1. Migrate civicrm_stripe_customers table to match on contact_id instead of email address. This can be re-run if necessary using StripeCustomer.updatecontactids API.
2. Migrate data from civicrm_stripe_subscriptions to use the recurring contribution (trxn_id = Stripe subscription ID). This can be re-run if necessary using StripeSubscription.updatetransactionids API.
## Release 5.1
*This was a limited release to selected clients in order to test new functionality. **Production sites should upgrade to 5.2 directly from 5.0**.*
### Changes:
* Use contact_id as reference in civicrm_stripe_customers and don't require an email address for payment.
* Drop old webhook code / endpoint at https://{yoursitename.org}/civicrm/stripe/webhook. You **MUST** update your webhooks to use the standard CiviCRM endpoint at https://{yoursitename.org}/civicrm/payment/ipn/XX (see [Webhooks and Recurring Payments](/recur.md) for details).
## Release 5.0
*This is the first release with a new maintainer (mattwire https://www.mjwconsult.co.uk) and repository move to https://lab.civicrm.org/extensions/stripe.*
**If upgrading from ANY version before 5.0 you should upgrade to this version first. It should be a safe upgrade for all sites on previous versions unless you are running a customised version of the extension.**
### Highlights:
* Fix all known "Stripe.js token was not passed".
* Tested support for Drupal 7 / Wordpress / Joomla for contributions/event payments.
* Improvements to recurring payments (though you will want to upgrade to 5.2 if using recurring payments as recurring payments has had a major rewrite for 5.2).
\ No newline at end of file
docs/testing.md 0 → 100644
+ 59
− 0
View file @ 260deb03
# TESTING
### PHPUnit
This extension comes with two PHP Unit tests:
* Ipn - This unit test ensures that a recurring contribution is properly updated after the event is received from Stripe and that it is properly canceled when cancelled via Stripe.
* Direct - This unit test ensures that a direct payment to Stripe is properly recorded in the database.
Tests can be run most easily via an installation made through CiviCRM Buildkit (https://github.com/civicrm/civicrm-buildkit) by changing into the extension directory and running:
phpunit4 tests/phpunit/CRM/Stripe/IpnTest.php
phpunit4 tests/phpunit/CRM/Stripe/DirectTest.php
### Katalon Tests
See the test/katalon folder for instructions on running full web-browser based automation tests.
Expects a drupal (demo) site installed at http://localhost:8001
1. Login: No expected result, just logs into a Drupal CMS.
1. Enable Stripe Extension: Two payment processors are created, can be done manually but processor labels must match or subsequent tests will fail.
1. Offline Contribution, default PP: A contribution is created for Arlyne Adams with default PP.
1. Offline Contribution, alternate PP: A contribution is created for Arlyne Adams with alternate PP.
1. Offline Membership, default PP: A membership/contribution is created for Arlyne Adams with default PP.
1. Offline Membership, alternate PP: A membership/contribution is created for Arlyne Adams with alternate PP.
1. Offline Event Registration, default PP: A participant record/contribution is created for Arlyne Adams with default PP.
1. Offline Event Registration, alternate PP: A participant record/contribution is created for Arlyne Adams with alternate PP.
1. Online Contribution Stripe Default Only: A new contribution record is created.
1. Online Contribution Page 2xStripe, Test proc, use Stripe Alt: A new contribution record is created. **FAIL:
Error Oops! Looks like there was an error. Payment Response:
Type: invalid_request_error
Code: resource_missing
Message: No such token: Stripe Token**
1. Online Contribution Page Stripe Default, Pay Later: A new contribution record is created.
1. Test Webform: A new contribution is created. *Partial test only*
ONLINE contribution, event registration tests
### Manual Tests
1. Test webform submission with payment and user-select, single processor.
1. TODO: Are we testing offline contribution with single/multi-processor properly when stripe is/is not default with katalon tests?
1. Test online contribution page on Wordpress.
1. Test online contribution page on Joomla.
1. Test online event registration.
1. Test online event registration (cart checkout).
#### Drupal Webform Tests
TODO: Add these as Katalon tests.
1. Webform with single payment processor (Stripe) - Amount = 0.
1. Webform with single payment processor (Stripe) - Amount > 0.
1. Webform with multiple payment processor (Stripe selected) - Amount = 0.
1. Webform with multiple payment processor (Stripe selected) - Amount > 0.
1. Webform with multiple payment processor (Pay Later selected) - Amount = 0.
1. Webform with multiple payment processor (Pay Later selected) - Amount > 0.
1. Webform with multiple payment processor (Non-stripe processor selected) - Amount = 0.
1. Webform with multiple payment processor (Non-stripe processor selected) - Amount > 0.
mkdocs.yml 0 → 100644
+ 24
− 0
View file @ 260deb03
site_name: Stripe Payment Processor (https://stripe.com)
repo_url: https://lab.civicrm.org/extensions/stripe
theme: material
markdown_extensions:
- attr_list
- admonition
- def_list
- codehilite
- toc(permalink=true)
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.tilde
- pymdownx.betterem
- pymdownx.mark
pages:
- About: index.md
- Installation: install.md
- Recurring Contributions (Subscriptions): recur.md
- Advanced:
- API: api.md
- Hooks: hooks.md
- Testing: testing.md
- Release Notes: release/release_notes.md
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment