A Guide To Connecting Stripe With Craft CMS

Setting Up a Stripe Account

Signing Up for a Stripe Account

Signing up for a Stripe account is quick and easy. To begin, go to stripe.com and click on the "Sign up" button in the top right corner. You'll be prompted to enter your email address and create a password. Stripe will then send a confirmation email to verify your address - be sure to click the confirmation link.

Once confirmed, you'll be asked to provide some basic personal and business information to finish setting up your account. This includes your name, business name, business website, phone number and business address. Stripe needs this info to be able to pay you out when you start processing payments.

After entering your details, Stripe may ask you to provide some form of ID verification like a passport or driver's license. This is to ensure security and prevent fraud. Once ID is verified, your Stripe account will be fully activated and you'll have access to the Stripe dashboard.

The Stripe dashboard is where you'll manage everything related to processing payments, tracking transactions, viewing reports and more. It has a clean, intuitive interface that makes it easy to find what you need.

Navigating the Stripe Dashboard

The Stripe dashboard is organised into different sections that group related tasks and information. Across the top you'll see the main navigation - this allows quick access to each area of the dashboard.

The overview section provides at-a-glance info on transactions, revenue and other key metrics. You can customise the cards shown here to suit your needs. The payments section is where you can view all incoming and outgoing payments in detail. You can search, filter and export transaction data for reconciliation or reporting.

The customers section stores any customer profiles you create in Stripe, along with their saved payment methods, subscriptions, invoices and more. This helps you easily manage recurring customers.

The billing section is where you can create and manage subscriptions, invoices, coupons and other billing tools. This comes in handy for SaaS or membership-style businesses.

The connect section allows you to onboard other platforms, apps or sellers to accept payments through your Stripe account. This facilitates marketplaces and split payments.The reports section offers pre-built reporting on payments, revenue, refunds, fees and other metrics. You can also create custom reports filtered by date, product, country and other parameters.

Generating API Keys

To integrate Stripe with an external platform like Craft CMS, you need API keys. These keys allow the platforms to communicate securely.

To generate your API keys, go to the "Developers" section in the Stripe dashboard. Here you'll see options to reveal and copy your publishable and secret keys.

The publishable key can be hardcoded into your website code or app. This allows you to securely collect payment details from customers.

The secret key should be kept private on your servers. This authorises requests to process charges, create customers, etc.

You can generate multiple API key pairs and deactivate ones you're not using for added security. Just be sure to sync any new keys across all integrated platforms.

With the publishable and secret keys, you can integrate Stripe checkout, subscriptions, invoicing and other features into your Craft site. Keys are generated per Stripe account, allowing you to keep test and live integrations separate.

This covers the basics of getting set up with a Stripe account, navigating the dashboard interface, and generating the essential API keys for integration. With these steps completed, you'll be ready to connect Stripe to your Craft CMS site and start collecting payments.

Installing the Stripe Plugin in Craft CMS

Finding the Official Plugin

When setting up Stripe in Craft CMS, it's important to use the official Stripe plugin to ensure full compatibility and support. This can be found in the Craft Plugin Store at https://plugins.craftcms.com.

To verify you have the right plugin, look for the developer name "Stripe" and plugin name "Stripe", with a green "Official" label. Avoid any similarly named plugins by other authors to prevent issues.

The official Stripe plugin has over 200,000 downloads and is actively maintained by Stripe to work seamlessly with the latest Craft CMS and Stripe API updates. Customer support is also available through Stripe in case any issues arise.

Before downloading, check the plugin page to ensure your Craft CMS version is supported. At the time of writing, the Stripe plugin supports Craft 2.4 through 3.7.x. Up-to-date version compatibility information can always be found on the plugin page.

Purchasing and Downloading

To purchase the Stripe plugin, you'll need to add it to your cart and complete checkout in the Craft Plugin Store. Pricing is $99 for a single-site license. Multi-site licenses are also available if needed.

After checkout, you can immediately download the Stripe plugin as a .zip file by clicking the "Download" button on your Craft Plugin Store account page. Make sure to download the file completely before attempting to install it.

You'll also receive a purchase confirmation email from the Craft Plugin Store containing a license key and download links. This key will be needed later when activating the plugin in your Craft control panel.

If you run into any issues purchasing, downloading or need to retrieve your license key, you can reach out to Craft Plugin Store customer support for assistance.

Installing and Configuring

To install the downloaded Stripe plugin in Craft, first unzip the .zip file on your computer. Then, in your Craft control panel go to Settings > Plugins and click the "Install" button.

Select the unzipped Stripe plugin folder. Craft will now upload and install the plugin files. When installation completes, go to Settings > Plugins and click on Stripe to open the plugin configuration page.

Here you can enter the license key from your purchase confirmation email which will activate the plugin. The Stripe plugin settings will then become available.

In the settings, you'll need to add the API publishable and secret keys generated from your Stripe account. You can also configure payment forms, webhooks, and other preferences.

Stripe offers thorough documentation within the plugin to guide you through the entire configuration process. This covers settings for checkout, subscriptions, invoicing and more.

With the official Stripe plugin installed and activated using your license key, the integration with Craft is now complete. Payments can be collected through Stripe by setting up payment forms that leverage the plugin.

The plugin bridges the gap between Craft CMS and Stripe, enabling smooth management of payments, customers, and billing all from your Craft control panel. Keeping the plugin updated ensures you always have access to the latest compatibility and features.

Connecting Stripe to Craft CMS

Adding API Credentials

To establish a connection between Stripe and Craft CMS, you first need to add your API credentials within the plugin settings.

In your Craft control panel, go to Settings > Plugins and open the Stripe plugin configuration. Then, open the “Credentials” tab.

Here you can enter the publishable and secret API keys that were generated from your Stripe dashboard. The publishable key allows Craft to securely collect payment details. The secret key authorizes requests to process payments, create customers, etc.

Double-check that you are adding the live version of your API keys if your Craft site is live. For test transactions, use your Stripe test keys instead.

Click “Save Keys” once entered correctly. Craft will verify the keys are communicating properly with the Stripe API. The connection between Stripe and Craft is now ready.

Mapping Payment Fields

With the API credentials in place, submitted payment data needs to be mapped from Craft to Stripe.

Under the plugin’s “Settings” tab, open “Checkout Form Mapping”. This allows you to match up corresponding fields between Craft and Stripe.

For example, you’ll want to map your Craft order name field to Stripe’s name field, and the customer email field to Stripe’s email field. This ensures data flows through correctly on checkout.

Address mapping is also important - make sure fields like address line 1, city, postcode all align between Craft and Stripe for accurate customer addresses.

Take care when mapping payment fields like card number, expiry date and CVC to their Stripe equivalents. This is required for payments to process.

You can reference Stripe’s API documentation to understand the required field names and formats within Stripe for mapping. Saving your field mappings will complete the integration setup.

Verifying the Connection

To verify your live Stripe connection is working properly before going live, process some test transactions using Stripe test keys and the Stripe webhook debugger.

Submit test checkouts using dummy payment details from https://stripe.com/docs/testing. Then, inspect the API requests and webhook events within Stripe to ensure payment data is passing through as expected.

Check that customers, charges and other API requests are being created properly in Stripe based on actions performed in Craft. Use Stripe logging features if needed to further debug the integration.

Monitoring webhook events in real-time is also useful. Stripe can alert you to webhook failures, customer creation, successful charges and more. Retest periodically to catch any issues.

With credentials configured, fields mapped, and the connection thoroughly tested with transactions, you can feel confident in launching your live Stripe-powered Craft CMS site.

Just swap in your live keys and you'll be ready to collect real payments. Keep the plugin updated and refer to Stripe's documentation for ongoing management best practices.

Creating Payment Forms in Craft CMS

Payment Form Templates

Craft CMS makes it easy to create Stripe-powered payment forms using built-in templates. Under Commerce in the control panel, go to Settings > Payment Forms.

Here you can select a pre-made template like "Checkout" for simple purchases or "Subscribe" for recurring subscriptions. There are also templates for donations, product launches and more.

The templates provide pre-configured Stripe checkout fields, validation, and UI elements needed to collect payments. They take care of the complex functionality behind-the-scenes.

For one-time purchases, the Checkout template is recommended. For memberships or SaaS signup flows, the Subscribe template handles recurring billing.

While templates provide the foundation, you can customize everything from the wording to styling to match your brand. Change labels, placeholders, help text and adjust field ordering as needed.

Reusable form components like radio buttons, dropdowns and text inputs make it fast to tailor the form. The templates take the busywork out of payment form creation.

Customizing Checkout Fields

Every element of the Stripe checkout fields can be customized within a payment form template in Craft.

For example, you can change the card number field from "Card number" to "Credit card number". Required field indicators, validation formats, and error messaging can also be tailored.

To brand the form, use CSS to style and layout the field containers, labels, placeholders and inputs. Adjust padding, widths, colours and more.

Make sure customizations don't conflict with Stripe requirements. For example, card number and expiry must use supported formats for payments to process.

For help text and instructions, Craft gives you full control over the wording and presentation. Guidance text can be added below inputs to guide customers.

Changes to labels and CSS will carry across to Stripe checkout for a consistent experience. Customizations make the checkout process resonate more with your users.

One-Time vs Recurring Payments

Setting up Stripe payment forms for one-time purchases versus recurring subscriptions requires slightly different approaches.

For one-time checkout, you can use the simplified Checkout template. This collects basic customer and payment details for single charges.

Recurring forms should use the Subscribe template, which includes additional fields like coupon codes and billing schedules needed for subscriptions.

The Subscribe template connects to Stripe Customer objects to manage subscribers and recurring billing. Checkout forms just create single charges without a customer profile.

Validation and fraud checking also differ. Recurring forms use Stripe Radar for extra fraud screening to prevent abuse. Usage limits may also be set for subscriptions.

Make sure one-time and recurring forms are well-labelled so users understand the billing model. Leverage Stripe's templates and documentation to implement the right flows for each.

With the ability to quickly spin up customized one-time and recurring payment forms, Stripe integration supercharges monetization in Craft CMS.

Accepting One-Time Payments with Stripe

Charging Credit Cards

Stripe makes it easy to securely accept credit and debit card payments for one-time purchases in Craft CMS.

Using a checkout or donation form powered by Stripe, customers can safely enter their card details. Stripe leverages industry-leading fraud prevention and 3D Secure to protect against fraud.

Card numbers, expiry, CVC and ZIP/postal code entered by the customer are encrypted and securely sent to Stripe for processing. This is all handled transparently through the Stripe integration.

Once submitted, Stripe will immediately attempt to authorize and capture payment from the card. No sensitive card data touches or is stored on your servers for maximum security.

Funds from successful credit or debit charges are deposited directly into your Stripe account balance. You can then deposit payouts to your bank account on a rolling basis.

Stripe also handles retry logic in case of declines or errors. This improves success rates and conversion for one-time payments.

Processing Transactions

When a customer completes your Craft CMS checkout form, Stripe takes over securely processing the transaction in the background.

As soon as the form is submitted, Stripe creates a charge using the payment method and amount configured in your form template.

Charges happen behind the scenes - customers simply see a confirmation that payment was successful after submitting details. Email receipts are also automatically sent.

In your Stripe dashboard, you can view every charge and its associated metadata like order IDs. The charge list gives you full visibility into transactions.

Stripe will immediately attempt to capture funds from the customer's card. If successful, the charge is marked "Paid" and deposited into your Stripe balance.

For any issues, webhooks allow Craft to programmatically update associated orders with the charge status for order management.

Managing Payment Statuses

Within the Craft control panel, you can view the status of Stripe charges associated with orders.

The order index page displays statuses like Paid, Failed, and Pending based on API data from Stripe. You can also view charge IDs and histories.

For orders marked "Paid", no action is required. These represent successful transactions.

For "Failed" orders, Stripe's automated retry logic may ultimately succeed, reversing the failure. If not, refunds can be issued.

Orders stuck in "Pending" may require manual review - for example, authorizing a 3D Secure payment.

Update payment statuses manually or via webhooks to keep order management in sync with real-time charge outcomes from Stripe.

With the power to securely accept one-time card payments and real-time visibility into associated charges, Stripe unlocks simple yet robust checkout monetization within Craft CMS.

Accepting Recurring Payments with Stripe

Setting Up Subscriptions

Stripe makes accepting recurring subscription payments simple within Craft CMS. Just enable the subscription functionality when configuring your Stripe plugin.

In Stripe, you'll first need to create products and prices for the plans subscribers can purchase. You can set up monthly, annual, or custom billing cycles.

Connect the subscription products to a payment form rendered in Craft using the "Subscribe" template. This allows site visitors to sign up.

When a customer submits the form, Stripe will automatically create a Subscription record and begin billing the customer based on your products.

Ongoing subscription management like cancellations, changes, and renewals are handled automatically by Stripe based on your settings. Webhooks sync changes back to Craft.

To implement add-ons, coupons, metered billing, or free trial periods, leverage the advanced options in the Stripe Dashboard. Subscriptions provide recurring revenue.

Creating Subscription Products

Before customers can subscribe, you need to configure your subscription plans and pricing in Stripe.

In your Stripe Dashboard, create Products for each subscription plan - for example, "Basic" and "Pro" plans. Configure the recurring price, billing interval, currency, and features.

For a multi-product business like SaaS, make a separate product for each software module or service that can be subscribed to.

You can also create discount coupons to provide promotional offers to subscribers. Coupons set percentage or fixed dollar discounts.

On the Craft side, a Subscribe payment form template makes it easy to present the subscription products, optional add-ons, coupons, and pricing.

Make sure Product IDs match between Stripe and Craft so customers are billed correctly. Now you're ready to accept recurring payments.

Managing Subscribers

The Stripe plugin adds helpful tools to Craft for managing subscription customers after checkout.

Under Commerce, you can see a list of all subscribers synced from Stripe. View their subscription status, history, invoices, and more.

Link subscriber profiles in Craft to user accounts for identity and access management. Set up groups to manage permissions.

Email subscribers directly from the control panel. Send targeted renewal reminders, upsell offers or subscriber-only newsletters.

Integrate a cancellations flow if desired. Automatically downgrade or revoke member access upon cancellation while retaining data.

Sync subscriber details, invoices, and subscription changes via webhooks for up-to-date member management and reporting in Craft.

With the ability to create flexible subscription products and easily manage customers, Stripe recurring payments supercharge SaaS, media, and membership sites using Craft CMS.

Customizing the Checkout Experience

Modifying Checkout Templates

The Stripe plugin provides checkout templates for Craft CMS that can be deeply customized to match your brand.

Using the template HTML structure and Liquid syntax, entire sections can be added, removed or reordered. You have full control.

For example, you can include an order summary, custom graphics, additional fields, and text/content blocks to guide customers.

Make sure not to remove required Stripe fields or parameters which would prevent payments from processing correctly. Refer to docs if unsure.

Beyond structure, use custom CSS to style all elements - input styles, colours, fonts, spacing, etc. This allows complete branded customization.

For optimal mobile checkout experiences, make sure to test responsiveness across devices. Follow Stripe's mobile best practices.

Adding Coupons and Promotions

Stripe integrates directly with Craft's native promotion and coupon tools to enable discounts at checkout.

First, create your promotion codes or per cent-off coupons in the Promotions area of the Craft control panel. Set the usage limits, validity dates, and discount amounts.

Then, add a coupon code field to the checkout or subscription form template and connect it to the promotion you created.

When customers apply a valid coupon during checkout, the discounted amount will automatically be sent to Stripe for processing.

Coupons applied to subscriptions can provide recurring discounts on every payment. Promotions encourage conversions and loyalty.

Styling the Payment Form

Use custom CSS to style and visually brand the Stripe elements embedded in your Craft payment forms.

For example, set darker label text, round the card number input borders, change placeholder colour, and customize the submit button appearance.

Make sure CSS selectors accurately target the Stripe form fields by inspecting elements. Avoid conflicts with other CSS.

You can find Stripe CSS variables for colour styling in their documentation. Use :focus and :active states to improve usability.

Apply box shadows, borders, background images, fonts, animations and any other CSS to visually distinguish your checkout form.

Match your overall site design - for example, using brand colours on labels, placeholders or the submit button. Consistent styling builds trust.

Leverage templates, custom code, promotions, and CSS styling to craft fully branded, conversion-optimized Stripe checkout experiences within Craft CMS.

Managing Transactions and Customers

Viewing Charges and Payments

The Stripe plugin for Craft CMS provides easy access to full transaction histories, charges, and payments directly in the control panel.

Under Commerce, the "Stripe" section lists every charge and payment event associated with your Stripe account, whether one-time or recurring.

Review the amount paid, payment source, status (paid, pending, failed), payment ID, associated order ID, and other metadata for each charge.

Click into individual charges to see even more detailed timelines - when issued, any disputes or refunds, decline reasons, and final outcomes.

Export charge history to a CSV for offline analysis and accounting. Use search and filters to zero in on specific charges or date ranges.

The payment overview gives powerful visibility into real-time transaction activity and histories from a central dashboard.

Issuing Refunds

Processing refunds for customers is simple within the Craft Stripe plugin - no need to leave the control panel.

Find the charge related to the order or transaction requiring a refund. Click the "Refund" button for that charge.

Enter the refund amount, whether full or partial. You can also include an optional refund reason for your records.

Stripe will immediately process the refund to the original payment source used by the customer, crediting their account.

The charge status will update to show the refund issued. Email the customer to confirm it has been completed.

Partially refunded charges will display the original amount and refunded amount separately for reconciliation.

For cancelled subscriptions or expired promotions, Craft can automatically trigger refunds based on certain events or timelines.

Managing Customer Profiles

With Stripe integration, Craft maintains synchronized customer profiles including payment sources, subscriptions, and personal details.

New customers created at checkout are added to the customer section in Craft's control panel. View their order history and billing details.

Saved payment cards, billing addresses, email, names and other relevant info stays up to date thanks to webhooks from Stripe.

Leverage customer records for identity management, re-engagement campaigns, and providing personalized experiences across your properties.

Implement single sign-on using Stripe customer IDs to securely authenticate members across Craft sites and apps.

Give customers the ability to self-manage payment methods, subscriptions, and account settings from a profile dashboard for a VIP experience.

Troubleshooting Stripe and Craft CMS

Common Integration Issues

When integrating Stripe with Craft CMS, there are a few common issues to watch out for:

• Incorrect API keys - Make sure you use live keys for a production site and test keys for staging/dev sites.

• Plugin conflicts - If using other plugins that modify checkout or payments, disable them to isolate conflicts.

• Field mapping errors - Double check form fields are mapped properly between Craft and Stripe.

• JavaScript conflicts - Third party scripts can sometimes interfere with Stripe JS, preventing load.

• Outdated plugins - Ensure both Craft and the Stripe plugins are fully updated to the latest compatible versions.

• Custom code bugs - Review recent code changes that may have broken functionality with Stripe integration.

• Configuration issues - improperly configured products, webhooks, and plugin settings can prevent payments.

Carefully going through integration steps, testing, and debugging can help identity and fix common issues.

Debugging Connection Errors

If the connection between Stripe and Craft is entirely broken, systematically debug the integration:

First, confirm the plugin is installed, enabled, and configured properly in Craft under Settings > Plugins.

Next, double check your publishable and secret API keys in the plugin settings match your Stripe Dashboard.

Try swapping the live keys for test keys and see if the connection re-establishes. This confirms whether the keys are valid.

Check Craft and Stripe plugin logs for more specific connection-related errors during requests. Enable Stripe debugging if needed.

Try disabling or uninstalling the plugin completely, then re-installing a fresh copy from the Plugin Store.

Restore a backup of your Craft CMS install from before the connection issues to rule out data corruption.

As a last resort, reach out to Stripe support with integration specifics - they can help diagnose cryptic API connection problems.

Fixing Payment Failures

If payments fail at checkout, first check for declined payment errors and have the customer update their card details and try again.

For repeated payment failures, ensure billing details like addresses and ZIP/postal code are accurately entered and match the cardholder's info.

Double check your Craft payment form template is mapped properly to Stripe fields, and no information is being lost.

Make sure to test with valid test card numbers when in development/staging mode per Stripe's docs.

On the Stripe Dashboard, dig into individual charge failure logs and decline reasons for more clues. Activate Radar for fraud checks.

If failures are intermittent, site traffic spikes may be triggering Stripe rate limits and declines. Scale upstream.

With structured debugging, failed payments between Craft and Stripe can be quickly identified and resolved to restore complete checkout conversion.