Stripe Elements – WS Form

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:

  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

Type

Choose ‘One Time’ or ‘Subscription’.

One time transactions perform a single charge of a customers credit card.

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.

Subscription transactions subscribe a customer to a Stripe Subscription. The subscription must be set up in the Stripe Dashboard before it can be used.

Note: Subscription payments must have customer fields mapped (See below). We recommend mapping at least name and email.

Subscription Price API ID(s)

To subscribe a customer to a Stripe Subscription, you need to enter a Price API ID.

Each subscription product you create in Stripe has a Price API ID.

You can find Price API IDs as follows:

  1. Log in to your Stripe Dashboard.
  2. Click on Products.
  3. Click on a product that contains a subscription (or create a new recurring payment product).
  4. Copy the API ID for the appropriate Price.
    WS Form PRO - Stripe Elements Add-On - Finding your Pricing API ID

To add the Price API ID in WS Form:

Note: The live and test environments in Stripe have separate products. When testing Stripe Elements using Price API ID’s, ensure you use ID’s that relate to the current environment you are using.

  1. Edit the ‘Stripe Card’ field in your form.
  2. Click the ‘Add’  icon at the bottom right of the ‘Subscription Price API ID(s)’ section.
  3. Paste the API ID into the setting.
  4. Click the ‘Save’ button at the bottom of the sidebar to save your changes.

It is possible to add more than Price API ID, but all of the prices must have the same duration.

It is also possible to use WS Form variables in the Price API ID field meaning you can use Select, Checkbox or Radio fields to give subscription options on your form.

Cancelling of subscriptions should be completed in the Stripe Dashboard.

Trial

You can add a trial period to a subscription using this feature. The options are:

  • No Trial
  • Number of Days
  • Use Plan Setting (This will use the legacy trial period associated with the price API ID you entered)
Initial Invoice Item Price API ID(s)

It is possible to add invoice items to the initial subscription transaction using this setting. This is done by adding Price API ID(s).

You can find Price API IDs as follows:

  1. Log in to your Stripe Dashboard.
  2. Click on Products.
  3. Click on a product you wish to add (or create a new one-time payment product).
  4. Copy the API ID for the appropriate Price.
    WS Form PRO - Stripe Elements Add-On - Finding your Pricing API ID

To add the Price API ID in WS Form:

  1. Edit the ‘Stripe Card’ field in your form.
  2. Click the ‘Add’  icon at the bottom right of the ‘Initial Invoice Item Price API ID(s)’ section.
  3. Paste the API ID into the setting.
  4. Click the ‘Save’ button at the bottom of the sidebar to save your changes.

You can add up to 10 items to this setting.

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.

Note: This option only appears if you have chosen a transaction type of ‘One-Time’. If you choose ‘Subscription’, the following customer field mappings should be completed.

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.

Field Wrapper

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

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

Show 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.

Variables

The Stripe Elements add-on introduces additional variables that you can use in actions such as messages and emails.

Name / VariableAdditional Information
Customer ID
#stripe_customer_id
Returns the customer ID used or created during the transaction.
Subscription ID
#stripe_subscription_id
Returns the subscription ID for subscription transactions.
Transaction ID
#stripe_transaction_id
Returns the transaction ID for one-time transactions.