Stripe Connector 


In this Article
Related Articles


Overview

With FormAssembly's Stripe Connector, you can easily process one-time credit card payments, set up recurring credit card payments through subscriptions, and create new customers in Stripe. This connector is available on all current plans and must be set up on a form-by-form basis.

Provided you have a Stripe account, you can follow the steps below to configure the connector and begin processing payments.

If you're new to FormAssembly connectors, or if you'd like a more in-depth look at how to set up your connector, you can watch our Video Tutorial for a detailed demonstration.

We also recommend reading more about how you can use reCAPTCHA to prevent spam submissions, as well as our Connector Labels to keep your connectors organized.


Getting Started

There are no definite restrictions on what your form may contain or what you may sell with it, but this service is better suited for simple situations, where:

  • You have a limited number of types of items to sell.
  • Items have a fixed price and a fixed or variable quantity.
  • Shipping & handling fees and taxes are applied to the total price.

Here are a few examples:

  • Selling intangible goods such as music (MP3s), software, eBooks, etc.
  • Charging a membership or an admission fee.
  • Charging a flat fee for consulting services.
  • Accepting donations.
  • Selling physical goods, to the extent that inventory is not an issue.

Requirements

In addition to a FormAssembly account, you'll also need a Stripe account to process payments.

Required Fields

As you build your form, make sure to collect the following credit card information:

  • Credit card number
  • Credit card expiration date (month and year in two separate fields)
  • Credit card security code
  • Cardholder's full name
  • Cardholder's email address
If you are building your form from scratch, check out our predefined content to easily add in a payment information section.  Or, you can also start with one of our three Stripe Templates, and customize it to your specific needs.

Configuration Steps

Once your form has been created, and you know what types of items or services you'll sell, you are ready to begin!

First, select the form you are working with and go to the Connectors page.

Next, add the Stripe Connector into the Form Submitted portion of the timeline and click Configure.


Step 1. Your Stripe Secret Key

The first piece of information you will be asked for is your Stripe Secret Key. This can be found in your Stripe account details. If you're using your Test Key, only test credit card numbers will be accepted.


Step 2. Credit Card Information

Once you've entered your secret key, you'll need to begin your field mapping so that the connector will know which fields in the form to pull information from. To do this, click on the dropdown menu next to each field and select the field in your form where this information will be entered.

You can also use our Formula Editor while you are mapping information to any of the fields in the Stripe connector.  If you are mapping to any repeated fields, please read this article to learn more about how they will work in conjunction with the Stripe connector.

Please note that only the credit card number and the expiration month and year are required for the connector. However, you can create additional required fields in your form if you need more information from your respondents.

During this step, you can also configure Customer Metadata if you'd like. Doing this will attach a set of key/value pairs to your customer's record in Stripe. You will be asked to provide a key and decide if the value will be defined in the connector or in the form.  

Because Stripe allows for up to 20 metadata key-value pairs, and created_by is one such a pair that is created automatically by FormAssembly, users can create up to 19 metadata fields in the Stripe Connector configuration screen.


Step 3. Customer Billing Address

Once you have mapped the credit card information, you can do the same for the customer's Billing Information, although this information is optional and not required. Again, you can click on the dropdown menus next to each field and select where you will define your values. In general, these values will be defined by fields in your form, and if you choose to map this information, you will need to select which field corresponds with which value.


Step 4. Shipping Information

If you choose to collect shipping information, you'll need to define your recipient's name either in the connector or in the form. Additionally, you can choose to use the billing information entered above, or map separate shipping information fields as well.

If you would like to map a field from your form that asks "Is your billing information the same as your shipping information" you can do that here as well. You will want to follow the mapping in the image below. If a user says "Yes" they are the same, you would map this as a "1" and use a "0" for "No."


Step 5. Subscription Information

You also have the option of adding subscription information for recurring payments. If you choose to add any subscriptions, you will need to define the Plan ID and Plan Quantity either in the form or in the connector.

For the Plan ID this will need to match a Plan ID you have previously created in Stripe. For example, if you have a plan in Stripe with the ID of "annualtwentyfive" for a $25 annual donation, then the value you send from the connector will need to match that exactly, capitalization included.

If you would like to have your users define the amount for a recurring subscription, this is possible, but your form will need a calculation to be set up (please see this demo form).  

To do this, on the Stripe side you will need to setup a monthly subscription for $1.  Then, in the connector mappings, your subscription ID will be set to whatever that $1 plan is named.  

The Plan Quantity should be set to the calculated field in your form that is determining how many payments will be made (see the demo form above).  In other words, if the user selects that they want to make a $100 recurring monthly payment, then the calculated field would show "100" and that field would be mapped to the plan quantity field in the connector. 

In general, for the Plan Quantity the default is set to 1. Unless the user is going to purchase multiple recurring subscriptions (as mentioned above), this should be set to "1" as the details for how often a recurring payment is made are set up on the Stripe side.

Plan Coupons and Plan Tax Percents can also be configured here as well, but they are not required.

Finally, as with Step 2, you can also choose to add Subscription Metadata in the form of key/value pairs.


Step 6. One-Time Charges

Finally, during step 6, you'll need to configure all of the single items and services you have available for purchase. At the minimum, you will need to define Item Name, Unit Price, and Quantity Ordered for each item you are selling.  The Item Name and Description fields are for your records only, and are not sent to Stripe.

You can choose to define your item price and quantity in the connector or in the form. If this information is being collected in the form, then you will need to select the field where the information is located. If you're defining the values in the connector, then you'll need to write in the values you would like.

For more information on field mapping and the basic set up of the Stripe connector for single and recurring payments, you can watch our Video Tutorial.

Your currency option will be automatically set to whatever your Stripe default currency is, but you have the option of selecting a specific currency if you would like to.

As with Steps 2 and 4, you can also choose to add Charge Metadata in the form of key/value pairs.

Once you've set up your recurring and/or one-time charges, tou're ready to save your connector and begin testing. Make sure the connector is set to enabled at the top!


Processing Single and Recurring Payments with a Form

It is possible to process both single and recurring payments within a single form and within a single connector.  You can read more about this setup here.


Connector Behavior

Once you have your connector configured, it's important to understand the general behavior of the connector and how information is being sent to Stripe.

First, every time a form is submitted, a new customer will be created in Stripe. This customer will be subscribed to one or multiple plans and/or a one-time charge will be made depending on your setup.

Your new Stripe customer will have their Description field set to one of the following form fields, which are ordered by priority:

  • Credit card holder's name
  • Shipping recipient's name

Please note that the credit card holder's name is an optional field, and shipping details can be absent altogether, so your description field will remain empty if this is the case.  

When you save your connector, you may notice that some fields in your form are automatically updated.  This is due to our automatic validation feature.


Auto-Created Form Fields

When the Stripe connector is added to the timeline, it automatically adds 3 fields to its associated form. Below is the list of the field names and their corresponding labels:
  • STRIPE_CUSTOMER_NN - Stripe Customer ID
  • STRIPE_SUBSCR_NN - Stripe Subscription ID(s)
  • STRIPE_CHARGE_NN - Stripe Charge ID

NN is the unique connector ID — so if multiple Stripe connectors are added to the form, they will not interfere with each other and will be executed sequentially in the order defined in the timeline.

If the connector has a label, the label will be added to the field caption. As a result, the 3 field names will remain the same, but their captions will be changed automatically each time a connector label is edited in the Stripe Connector configuration screen.

For example, if the connector ID is 23 and the label is donation, then the following fields will be created:
  • STRIPE_CUSTOMER_23 - Stripe Customer ID (donation)
  • STRIPE_SUBSCR_23 - Stripe Subscription ID(s) (donation)
  • STRIPE_CHARGE_23 - Stripe Charge ID (donation)

Field Values

Once the Stripe Connector executes successfully, the corresponding values will be saved in the form response. For example:

  • Stripe Subscription ID(s) = sub_5trum894btcA4p, sub_5tru1SyK09nj9a
  • Stripe Charge ID = ch_5truZl8zVBghh6
  • Stripe Customer ID = cus_5tru3ohh8x1xGN

- Subscription ID(s) is either one or multiple comma-separated IDs.
- Customer ID is the ID of the customer created automatically with every form submission.
- Charge ID is the ID of the charge containing all items for sale, if there are any.


Video Tutorial

Note: It is now possible to have recurring payments set to be a user defined amount, contrary to what the video says. Please see the above section on recurring payments for more information.

Troubleshooting

If you receive the connector error, "Sending credit card numbers directly to the Stripe API is generally unsafe. We suggest you use test tokens that map to the test card you are using." you can resolve this error using the following steps.

Login to your Stripe account, and choose to enable "Process payments unsafely" under your dashboard settings.

You will then need to check the three boxes and choose that "Someone else built my Stripe integration."  You can then enter "FormAssembly" into the text field and click "Process payments unsafely":

Despite being labeled as "unsafe" all payments will still be processed securely. FormAssembly is PCI compliant, and all data collected and sent to stripe is secure.

Terms of Service · Privacy Policy