Stripe ElementsPRO

This knowledge base article relates to the WS Form Stripe Elements add-on. Click here to purchase this add-on.

Note: You must serve the page containing the payment form over HTTPS. In short, the address of the page containing Stripe Elements must start with https:// rather than just http://. For more information, click here.

The Stripe Elements add-on allows you to accept credit card payments from your forms. You can either charge a fixed amount using the button in isolation, or you can use the WS Form E-Commerce fields to produce more advanced cart options.

Installation

The WS Form Stripe Elements plugin is installed in the same way as installing the WS Form PRO plugin.

Once installed you will need to activate the license for the plugin. When you purchase the Stripe Elements add-on, you will be given a license key. If you have lost your license key(s), click here.

To activate your license key:

  1. Click ‘WS Form’ in the WordPress administration menu.
  2. Click ‘Settings’.
  3. Click the ‘Stripe Elements’ tab at the top of the page.
  4. Enter your license key.
  5. Click the ‘Activate’ button.

If your license key fails to activate, please ensure you are using the correct license key and not your WS Form PRO license key.

Configuring Stripe Elements

In order to use the Stripe Elements button, you first need to enter your Stripe publishable keys.

If you do not yet have a Stripe account, register for a new account.

To obtain your API keys:

  1. Log in to your Stripe account.
  2. From your Dashboard, click ‘Developers.’
  3. Click ‘API Keys.’

To enter your publishable keys (you do not need to enter your secret keys):

  1. Click ‘WS Form’ in the WordPress administration menu.
  2. Click ‘Settings’.
  3. Click the ‘Stripe Elements’ tab at the top of the page.
  4. Enter your test and live publishable key.
  5. Click the ‘Save’ button.

Adding The Stripe Elements Fields

Once configured the  Stripe Elements fields will appear under the ‘E-Commerce’ section of the toolbox when editing a form. Two fields types are added:

  • Stripe Card – The user enters their credit card details here
  • Stripe Submit – The user clicks this to submit their credit card details

`You can place the Stripe Card and Stripe Submit fields anywhere you like on the form. An example layout is shown below:

Stripe Elements - Fields

Settings

The majority of the settings are found in the Stripe Card field settings. To access the settings sidebar, click the settings  icon on the Stripe Card field.

The Stripe Submit field acts like a regular custom button field type. Please refer to that field type for more information about the settings.

The Stripe Card field settings are split into Basic and Advanced tabs in the sidebar as are detailed below:

Basic

The basic tab contains settings that the majority of WS Form users will need to control a field. The settings are as follows:

Label

This is the label shown above the credit card entry field. As well as entering a label into this field, you can also double click the label of the field in the editor. You should enter an easy-to-understand label for your field, for example, ‘Credit or Debit Card’.

Render Label

If enabled the label will be shown on your form. If you do not want the label to appear for a particular field, uncheck this box.

Label Position

There are five options you can choose from for positioning your label:

  • Default
  • Top
  • Left
  • Right
  • Bottom

The default position will place the label set in the Form Settings advanced tab. For new forms this will be the ‘Top’ positioning.

Note that when using some frameworks, some label positions may not be available.

Label Width

If your label position is set to left or right, you can specify how wide the label will be. You can consider the overall width of the label and the field to be 12 columns (or whatever value is set in Form Settings). By default, labels are rendered at 3 columns wide (1/4 width), which means the field itself is 9 columns wide (3/4 width). You can change the width of the label using this setting.

To change the default width of all labels in your form:

1. Click the form settings icon.
2. Click the ‘Advanced’ tab.
3. Scroll down to ‘Default Label Width’ and change the setting.
4. Click ‘Save’ at the bottom.

Hidden

If checked, the field will be hidden on the form. It can be shown again using conditional logic or your own JavaScript.

Help Text

The help text setting enables you to add smaller text under the field to assist the website visitor in completing that field.

As well as inserting plain text into this field, WS Form also provides extensive functionality for adding character and word count information. Click here to learn more about this functionality.

WS Form variables can be entered into this field.

Transaction

Amount To Charge

By default this field is blank, and the Stripe Elements button will charge the amount calculated by the e-commerce fields on your form (the same as entering #ecommerce_cart_total). For example, you might have a single price field for making a donation, or a more elaborate form with prices, quantities, and subtotals.

You can also enter a fixed amount into this field.

WS Form variables can be entered into this field.

Description

Enter the description of the transaction in this field. For example: Payment To My Blog.

WS Form variables can be entered into this field.

Customer

Create Customer

If checked, a customer record will be created using the mapping settings below. Creating a customer record in Stripe makes cross-referencing transitions much easier. The following mapping settings are optional.

Name

Use this field to specify the name of the payer.  If you have text fields for first and last names, you would enter something such as:

#field(1) #field(2)

WS Form variables can be entered into this field.

Email

Choose an email field from your form to use for the payer’s email address.

Phone

Choose a phone field from your form to use for the payer’s phone number.

Description

Optionally, enter a description for the customer.

WS Form variables can be entered into this field.

Billing Address Mapping

Use the billing address mapping option to specify which fields on your form relate to the different parts of the billing address.

To map your form fields to Stripe billing address fields:

  1. Click the ‘Add’  icon at the bottom right of the billing address mapping section.
  2. In the left-hand column, select a field from your form.
  3. In the right-hand column, select the corresponding Stripe billing address field.
  4. Repeat this process for each field on your form.
  5. Click the ‘Save’ button at the bottom of the sidebar to save your changes.
Shipping Name

Use this field to specify the shipping name of the payer. In most cases you would enter the same value as entered in the ‘Name’ field above.

WS Form variables can be entered into this field.

Shipping Phone

Choose a phone field from your form to use for the payer’s phone number.

Shipping Address Mapping

Use the shipping address mapping option to specify which fields on your form relate to the different parts of the shipping address.

To map your form fields to Stripe shipping address fields:

  1. Click the ‘Add’  icon at the bottom right of the shipping address mapping section.
  2. In the left-hand column, select a field from your form.
  3. In the right-hand column, select the corresponding Stripe shipping address field.
  4. Repeat this process for each field on your form.
  5. Click the ‘Save’ button at the bottom of the sidebar to save your changes.

Advanced

Styles

Use the ‘Styles’ settings to change the design of the credit card entry field.

Vertical Alignment

The vertical alignment option allows you to choose how this field will be vertically aligned in relation to fields in the same row. The options are:

  • Top
  • Middle
  • Bottom
Icon Hidden

If checked, the credit card icon will be hidden from the credit card entry field.

Icon Style

This controls the appearance of the icon in the credit card entry field. Options are either ‘solid’ or ‘default’.

Classes

For developers WS Form allows you to add your own classes to fields.

Wrapper CSS Classes

The wrapper CSS class setting enables you to add a class (or classes) to a field wrapper. Field wrappers are sections of HTML added around a field to position them on the page. To add multiple classes, add a space between the class names.

Field CSS Classes

To add a class to the actual field element itself, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Transaction

Zero Amount

You can configure how WS Form should handle zero amounts for Stripe Elements buttons. In some cases you may wish to show an error message (e.g., a donation amount is set to zero). In other cases you may wish to still submit the form (e.g., if something is determined to be free). Select the appropriate action from the pull-down list.

Zero Amount Message

If you opt to show an error message, enter the error message you would like be shown here.

Messages

Error Messages

WS Form PRO processes any error messages as standard WS Form messages. The error message settings match those of the ‘Show Message‘ action. You can configure these options to change how the error messages are displayed to users.

Validation

Render Invalid Feedback

Invalid feedback text is shown when the credit card information entered is not valid, or if a transaction fails. If this setting is checked, invalid feedback is shown under the field.

Breakpoints

The breakpoint settings define the width of a field and also what the offset (how many columns from the left-hand side of the form or the previous field) of a field is for each breakpoint. For more information about the breakpoint settings and capabilities of WS Form, click here.