Stripe Import¶
Automatically import data from Stripe. This extension allows you to import data that is held in Stripe but might not be in CiviCRM. For example if you use the same Stripe account with other systems (eg. Shopify, WooCommerce, in-person sales etc.) you can have that data automatically imported into CiviCRM and matched with contacts and existing data.
It is extensible via hooks and can be configured in various ways.
A set of API functions and scheduled jobs are provided to get you started. Currently supported are Stripe Customers, Subscriptions and Charges.
The import process can be run automatically through scheduled jobs and manually through scripts and the API.
The extension is licensed under AGPL-3.0.
Installation¶
Learn more about installing CiviCRM extensions in the CiviCRM Sysadmin Guide.
You must use the "master" branch of the Stripe extension (which will be 6.11 release):¶
https://lab.civicrm.org/extensions/stripe/-/tree/master
To disable membership updates make sure you have applied:¶
https://github.com/civicrm/civicrm-core/pull/30085
Getting Started¶
Stripe Configuration settings¶
The Stripe configuration has to be set up at civicrm/admin/setting/stripe. Apart of the general settings for Stripe processing, you have to configure the following options for Stripe Import:
[ ? ] Record payments using the Payout currency
not selected: Contributions are recorded in the currency the donation was matched
selected: Contributions are recorded in the currency associated with your Stripe account - while the original amount and currency are saved in a custom field at the entity Contribution Financial Trxns
[ X ] Stripe Import: Automatically create missing contact
Should be selected in order to process payments from contacts not yet in civicrm
[ ] Stripe Import: Automatically match missing contribution
Typically not needed.
[ ] Stripe Import: Automatically create missing contribution
Typically not needed.
[ X ] Stripe Import: Import subscription charges using Charge importer
By default Stripe Charges linked to subscriptions are ignored by the Charge importer as they are handled by the subscription importer. If you enable this setting the Charge importer will also import charges that are linked to subscriptions (but without creating the recurring contribution).
[ ] Stripe Import: Send Receipt when importing a successful charge
Careful: Stripe already sends receipts by default. Sending receipts through CiviCRM requires additional configuration.
Stripe Import: Default financial type
Default financial type is required. If financial type was not specified or cannot be detected automatically use this one.
Stripe Import: Default Payment Instrument
Enter the payment processor ID of Stripe (see: civicrm/admin/options/payment_instrument)
API calls for importing Stripe Charges¶
The Stripe import charges are executed by an APIv3 call. You can execute this directly using the API Explorer (however for larger amounts of data you might have a timeout).
For regular processing, you should call this API using "scheduled jobs".
Regular processing¶
Basically, the stripe payments are available directly after the stripe online payment occured.
The "import charges" API call therefore can be applied regularly (e.g. "every time cronjob is run" or "every hour"). Example configuration:
Name: Stripe: Import Charges
API Call Entity: Stripe
API Call Action: importcharges
Command parameters:
ppid=2
created_after= -1days
limit=500
Regular processing - asynchronous payments¶
Please note that Stripe payments are processed “asynchronously” in some cases and remain in “pending” status for a longer period of time. For example, SEPA payments are subject to a delay of 7–12 days before they are actually debited and the payment status in Stripe is changed to “successfully completed.”
Therefore, you should call the API "again" after 10 days to collect all of these payments. In general, it is sufficient to run this import daily, but you have to give a higher limit in order to make sure to get all the pending payments.
Example configuration (daily)
Name: Stripe: Import Charges (collect async payments)
API Call Entity: Stripe
API Call Action: importcharges
Command parameters:
ppid=2
created_before= -10days
limit=2000
The limit must be set carefully to ensure that no payments are omitted, taking into account the expected number of payments. A limit that is too high could lead to performance problems, for example.
Known Issues¶
Subscription import for memberships renews the membership.¶
This is because Payment.create triggers a "Contribution Completion" which in turn triggers a membership renewal.
Workaround: https://github.com/civicrm/civicrm-core/pull/28607
But we'll need a way to conditionally enable/disable this as in "normal" operation we should renew the membership. But for initial import we don't want to.
Customisation¶
You can listen to the following events to customise the import process:
civi.stripeimport.startimport¶
Currently only implemented for subscription import
This event is dispatched at the start of each import.
It can be used to setup or change things before processing import.
For example, you could remove the default listener for civi.stripeimport.membershipauto in order to modify the default processing.
civi.stripeimport.membershipauto¶
Currently only implemented for subscription import
This event is dispatched if membershipauto is selected as an input parameter and no membership ID is specified.
A default listener is implemented in \Civi\StripeImport\MembershipSubscriber which will
select the membership linked to the recur if available or the latest current membership by ID.
Support and Maintenance¶
This extension is supported and maintained with the help and support of the CiviCRM community by MJW.
We offer paid support and development as well as a troubleshooting/investigation service.