Freeform for Craft

5.x ✓ Latest

• 5.x✓ Latest
• 4.x
• 3.xRetired
• 2.xRetired
• 1.xRetired

Plugin Store

Integrations

# Stripe Payments ProImproved in 5.0+

Key Features

A list of the key features.

Requirements

Requirements to use Stripe on your site.

Best Practices

Best ways to implement Stripe.

Customization

How to customize the appearance.

Setting Up

How to get started with Stripe.

Templating

Special properties available in templates.

Email Notifications

Using email notifications with Stripe.

Testing

How to test Stripe in your forms.

# Key Features

Freeform Payments uses the Payment Element approach from Stripe. The Payment Element is a UI component that accepts 40+ payment methods, validates input, and handles errors. This means that in addition to accepting credit cards, it will allow you to enable support for Stripe Link, Apple Pay, Google Pay, PayPal (within Europe), bank payments, deferred payments and many other options. Within minutes you can have anything from a form accepting donations to a membership registration form that has users pay for a subscription at any interval. The possibilities are endless!

40+ Payment Methods New!

Accept credit cards, Stripe Link, Apple Pay, Google Pay, PayPal (within Europe), bank payments, deferred payments and more! Learn more →

Secure Processing

All payment processing goes securely through Stripe. Freeform does not gain any access to any sensitive credit card or banking information.

Plug & Play

No technical knowledge is required to enable Stripe for your site. Follow our simple instructions and you'll be ready in minutes!

One-time Payments

Allow users to select or specify their own one-time payment. This could be for accepting donations, paying invoices, selling products and more!

Subscriptions

Allow users to select or configure their own recurring payments. This could be for memberships, donations, services and more!

Choice of Payment New!

Optionally allow users choose whether their payment is one-time, recurring, or done offline (not processed in your form).

Customizable

The Stripe field is highly customizable and even comes with a style guide and several built-in settings to control its appearance to match your site.

Map Freeform Data to Stripe

Easily map Freeform fields to Stripe fields to populate more customer information for the transaction/customer profile in Stripe.

Email Notifications

Send email notification to users about the success or failure and payment details of their payment transaction. No sensitive payment data will be included.

# Requirements

The Freeform Stripe integration has the following requirements:

• Freeform Pro edition.
  • If you're using another edition, you can switch/upgrade for the difference in price.
• Your own Stripe account.
• All API requests must be made over HTTPS. Testing can be done while using HTTP in Test Mode, however.
• Publicly accessible site is required to fully test or use Stripe.
  • You can forego webhooks testing if you like, however, and use a non-public local dev site.
  • When using on a local dev site, you will need to use a domain extension like .test in order for Stripe to recognize it.
  • If using a local dev machine, you can work around this by using a service like ngrok. You can still access your site via the local dev URL, as long as the public version is working and Stripe is aware of it.
• When using multi-page forms, the Stripe Element field should be placed on the last page of the form.
• The built-in Success Behavior setting will be ignored, as a Success and Fail Redirect URL path will need to be specified.

# Best Practices Recommended

The following are best practices when implementing the Stripe Element field to accept payments in your form.

# Place Stripe field on Last Page

Stripe makes some strong recommendations and assumptions that the Stripe Payment Element will only be displayed once the payment amount is determined and payment is ready to be made (on the last page of a multi-page form). Therefore, it works best when its placed on the last page inside of a multi-page form.

If you choose not to do it this way, some Stripe behaviors are worked around to ensure the feature still works:

• The Stripe Payment Element field will not load if there is no payment amount entered or selected (when allowing the user to specify). When possible, either default the Amount field to something other than 0 or empty OR ensure that the Amount field is on an earlier page than the Stripe Payment Element field so it is populated in time. If the Amount field is empty or 0, the Stripe Payment Element field will display the message: Could not load payment element.
• If allowing users to dynamically configure payment amount and/or interval when the Stripe Payment Element field is in the same page, the form will temporarily disable each time one of those fields is modified and the Stripe Payment Element field will reload.
• The Stripe.com dashboard will display an Incomplete or Canceled transaction each time the Stripe Payment Element field is loaded to a user and NOT completed or a payment amount or interval is changed while the Stripe field is present. To prevent this, avoid showing the Stripe Payment Element field and keep it on the last page of a multi-page form.

# Conditional Rules for Multiple Payment Options

It's possible to allow multiple payment options inside the same form. For example, you could include both a one-time and subscription payment option in the same form. However, simply show and hide the Stripe payment fields with conditional rules.

# Customization

The Stripe Payment Element allows for customization to fit your site's styles and needs.

# Appearance

The appearance of the Stripe Payment Element can be customized to match your site. Choose a theme or update specific details.

# Layout Options

You can customize the Payment Element's layout to fit your desired flow. The following image is the same Payment Element rendered using different layout configurations.

# Payment Methods

The Payment Element displays every payment method that's activated and available (handled inside the Stripe.com website dashboard). It automatically sorts these payment methods by relevance to your customer's location and locale. For instance, if a customer in Germany is paying in EUR, they see all the active payment methods that accept EUR, starting with ones that are widely used in Germany.

# Apple Pay & Google Pay

The Stripe Payment Element includes built-in support for Apple Pay and Google Pay.

# Setting Up

# Setting up the Payment Gateway

The following instructions assume you already have a Stripe account. You can add the Stripe integration by doing the following:

Prepare Stripe

Open up another browser tab and go to your Stripe account:

• On the top menu, click on the Developers button. On the next page click API Keys.

TIP

Stripe can be run in Live mode or Test mode. To toggle between Live and Test mode, click the Test mode toggle at the top of the page. When doing this, the Publishable key and Secret key will switch between live and test as well. We strongly recommend switching Stripe to Test mode first, and testing your site with those keys instead.

• Copy the token for Publishable key (e.g. pk_test_fs7f6f8g8dfg68g68d76dgd8) and paste into the Public Key field inside Freeform.
• Copy the token (click Reveal test key button to reveal) for Secret key (e.g. sk_test_af7fa7gfdo78g6ddfg6d8d87) and paste into the Secret Key field inside Freeform.

TIP

Consider using an Environment Variable for these settings instead. Then, store Live keys on production and Test keys on local dev environments.

# Setting up the Form

Setting up your form to collect payments will generally consist of the following:

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<h2>Customer Information</h2>
<ul>
    {% for field in allFields %}
        <li>{{ field.label }}: {{ field.labelAsString }}</li>
    {% endfor %}
</ul>
<hr />
{% if payments %}
    <h2>Payment Information</h2>
    <ul>
        <li>Amount: ${{ payments.amount }} {{ payments.currency }}</li>
        <li>
            Card ending in: •••• {{ payments.card }}
            ({{ payments.status }}{% if payments.errorMessage|length %} - {{ payments.errorMessage }}{% endif %})
        </li>
    {% if payments.type == "subscription" %}
        <li>{{ payments.planName }} ({{ payments.interval }})</li>
    {% endif %}
    </ul>
{% endif %}

# Configuring Payment Methods

The Stripe Payment Element allows you to accept 40+ payment methods, including credit cards, Stripe Link, Apple Pay, Google Pay, PayPal (within Europe), bank payments, deferred payments and more!

To enable additional payment methods for your site, visit the Stripe Payment Methods settings area (Stripe → Settings Cog icon (top right nav) → Settings → Payment Methods (under Payments section)).

Some payment methods such as Apple Pay require domains to be registered. You can configure this by visiting the Stripe Payment Method Domains settings area (Stripe → Settings Cog icon (top right nav) → Settings → Payment Method Domains (under Payments section)).

• Registering domains for payment methods
• Full list of available Payment methods

# Mapping Payment Data to Other Integrations

Stripe payment data is available to map to other integrations such as CRMs as well. The following options will become available to map:

• Amount
• Interval
• Interval Count
• Card Token
• Card Last 4
• Card Type
• Stripe Charge ID
• Stripe Customer ID
• Stripe Transaction Hash

# Templating

The following properties are available for use inside email notification templates and front end templates (Submission object):

# Submission Data Example

For displaying the submission data, your code may look something like this:

{% set submissionId = craft.app.request.segment(3) %}
{% set payments = freeform.payments(submissionId) %}
{% if payments %}
    <h2>Payment Information</h2>
    <ul>
        <li>Amount: ${{ payments.amount }} {{ payments.currency }}</li>
        <li>
            Card ending in: •••• {{ payments.card }}
            ({{ payments.status }}{% if payments.errorMessage|length %} - {{ payments.errorMessage }}{% endif %})
        </li>
    {% if payments.type == "subscription" %}
        <li>{{ payments.planName }} ({{ payments.interval }})</li>
    {% endif %}
    </ul>
{% endif %}

# Rendering Stripe Payment Element in your Form Improved in 5.0+

For rendering the Stripe Payment Element field inside your form, it simply works like any other field:

{{ field.render() }}

If you wish to make any customization to the handling of Stripe payment fields, you can use the Template Overrides feature and do this at form level:

{{ form.renderTag({
    fields: {
        "@stripe": {
            attributes: {
                input: {
                    "-class": "form-control bg-dark-subtle",
                },
            },
        },
    },
}) }}

Or at the field level by using a conditional like this:

...
{% elseif field.type == "stripe" %}`
    {{ field.render({
        attributes: {
            input: {
                class: "my-stripe-class",
            },
        },
    }) }}
{% else %}
...

# Styling the Stripe Element Improved in 5.0+

To style the Stripe Payment Element, you'll need to use the Freeform JS Plugin and apply Stripe's Appearance API variables to the elementOptions and paymentOptions listeners.

# elementOptions.appearance

Below is a list of commonly used variables. See Stripe documentation for a complete list of other variables.

The rules option is a map of CSS-like selectors to CSS properties, allowing granular customization of individual components. After defining your theme and variables, use rules to seamlessly integrate Elements to match the design of your site.

The selector for a rule can target any of the public class names in the Element, as well as the supported states, pseudo-classes, and pseudo-elements for each class. For example, the following are valid selectors:

• .Tab, .Label, .Input
• .Tab:focus
• .Input--invalid, .Label--invalid
• .Input::placeholder

The following are not valid selectors:

• .p-SomePrivateClass, img - only public class names can be targeted
• .Tab .TabLabel - ancestor-descendant relationships in selectors are unsupported
• .Tab--invalid - the .Tab class does not support the --invalid state

See Stripe documentation for a complete list.

# paymentOptions.layout

Options for creating the Payment Element.

Full documentation can be found here: Stripe Elements Appearance API

# Example

<script>
var form = document.querySelector('[data-id="{{ form.anchor }}"]');
if (form) {
    form.addEventListener("freeform-stripe-appearance", function (event) {
        event.elementOptions.appearance = Object.assign(
            event.elementOptions.appearance,
            {
                variables: {
                    colorPrimary: "#0d6efd",
                    fontFamily: "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,\"Helvetica Neue\",Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\",\"Segoe UI Symbol\",\"Noto Color Emoji\"",
                    fontSizeBase: "16px",
                    spacingUnit: "0.2em",
                    tabSpacing: "10px",
                    gridColumnSpacing: "20px",
                    gridRowSpacing: "20px",
                    colorText: "#eaeaea",
                    colorBackground: "#1d1f23",
                    colorDanger: "#dc3545",
                    borderRadius: "5px",
                },
                rules: {
                    '.Tab, .Input': {
                        border: '1px solid #6c757d',
                        boxShadow: 'none',
                    },
                    '.Tab:focus, .Input:focus': {
                        border: '1px solid #0b5ed7',
                        boxShadow: 'none',
                        outline: '0',
                        transition: 'border-color .15s ease-in-out',
                    },
                    '.Label': {
                        fontSize: '16px',
                        fontWeight: '400',
                    },
                },
            }
        );
        event.paymentOptions.layout = Object.assign(
            event.paymentOptions.layout,
            {
                defaultCollapsed: true,
                visibleAccordionItemsCount: 3,
            }
        );
    });
}
</script>

# Email Notifications

# Example Usage

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<h2>Customer Information</h2>
<ul>
    {% for field in allFields %}
        <li>{{ field.label }}: {{ field.labelAsString }}</li>
    {% endfor %}
</ul>
<hr />
{% if payments %}
    <h2>Payment Information</h2>
    <ul>
        <li>Amount: ${{ payments.amount }} {{ payments.currency }}</li>
        <li>
            Card ending in: •••• {{ payments.card }}
            ({{ payments.status }}{% if payments.errorMessage|length %} - {{ payments.errorMessage }}{% endif %})
        </li>
    {% if payments.type == "subscription" %}
        <li>{{ payments.planName }} ({{ payments.interval }})</li>
    {% endif %}
    </ul>
{% endif %}

# Testing

It's best practice to test out your form and Payments implementation to ensure it works correctly and as expected. Please visit the Stripe Testing documentation for a full reference of how to test your forms and get a feel for how it handles failures, etc. Also be sure to toggle the Test mode button in the Stripe account area for testing, as Stripe will provide you with a different set of keys for testing mode.

For quick reference, here is some general testing data:

# Testing successful purchases

• Card: 4242424242424242
• Expiry Date: (anything in future, e.g. 2/42)
• CVC: (any 3 digits, e.g. 242)

# Testing for errors and responses

• Card: 4000000000000002 - Charge is declined with a card_declined code.
• Card: 4100000000000019 - Results in a charge with a risk level of highest. The charge is blocked as it's considered fraudulent.
• Card: 4000002760003184 - Test for Strong Customer Authentication (SCA).
  • A full list of card numbers for more scenarios can be found in the Stripe documentation.

# Troubleshooting

When viewing Payment individual submissions in the control panel, the right side of the page will display a more detailed error for failed payments. If you think there might be an issue with Freeform or your implementation, this may help you look for patterns and troubleshoot.