FAQ

Permissions

To accept payments using Stripe you must have "make online contributions" permission enabled. No other permissions are required.

Terminology

CiviCRM <=> Stripe

• A CiviCRM Recurring Contribution is the equivalent of a Stripe Subscription.
• A CiviCRM Contribution is the equivalent of a Stripe Invoice.
• A CiviCRM Payment is the equivalent of a Stripe Charge.
• A CiviCRM Contact is the equivalent of a Stripe Customer.

Field	CiviCRM entity	Stripe	CiviCRM field
Subscription ID	ContributionRecur	Subscription ID	trxn_id/processor_id
Order Reference/Invoice	Contribution	Order Reference	Payment.order_reference
Transaction ID	Contribution	Transaction ID	trxn_id
Transaction ID	Payment	Transaction ID	trxn_id
Order Reference	Payment	Order Reference	order_reference

Stripe

• Charge: A charge / payment that shows on a users credit card.

Invoices and Charges?

For a one-off contribution an invoice is NOT created, so we have to use the Stripe Charge ID. In this case we set the contribution trxn_id = Stripe Charge ID.

For a recurring contribution an invoice is created for each contribution:

• We set the contribution trxn_id = Stripe Invoice ID.
• We set individual payments on that contribution (which could be a payment, a failed payment, a refund) to have trxn_id = Stripe Charge ID

Uncaptured Payments / Charges

Stripe uses PaymentIntents to pre-authorise and authenticate a card.

These paymentIntents work in the same way as a pre-authorisation on Credit Card (such as a damage deposit on car-hire). For this reason they can be problematic when there are multiple failures as a customer card will remain authorised for 7 days and shows as a charge on the customer card. They can be manually cancelled via the Stripe Dashboard.

To mitigate this the Stripe extension tracks and records all paymentIntents created through CiviCRM and manages them using a scheduled job Job.process_stripe.

The defaults for this are to cancel uncaptured payments after 1 hour and clear out old records (from the CiviCRM database) after three months.

Payment Metadata

When we create a contribution in CiviCRM (Stripe Invoice/Charge) we add some metadata to that payment.

• The statement descriptor contains a parsable contactID-contributionID and then part of the description.
• The description contains the description, a parsable contactID-contributionID and then the CiviCRM (unique) invoice ID.

Customer Metadata

A new Stripe Customer is created the first time a contribution is created by them in CiviCRM.

When is Stripe metadata updated?

• Each time a new payment/contribution is created.
• If the primary contact email address is updated.

What metadata is sent to Stripe?

The following metadata is created for a Stripe Customer:

• Contact Name, Email address
• Description (CiviCRM: + site name).
• Contact ID.
• Link to CiviCRM contact record.
• CiviCRM version info (eg. 5.18.3 6.2).

In addition, if you have enabled receipts (see Setup) the email address will be sent to Stripe and used to send a receipt to the contact.

Postcode and Billing Address

Stripe performs advanced validation and detection of postal/zip code and whether it is required or not. So we use the postal code value from the stripe "element" as the "master".

The Stripe "element" collects the billing postcode. CiviCRM uses the following logic for the billing postcode: * If contact has existing billing address copy existing postcode to stripe element and disable the standard postcode field on the form. * If contact has no billing address (or blank postcode) hide the standard postcode field and copy it from the stripe "element" when it is filled in.