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.
How it Works
The Stripe Elements payment process works as follows:
- Customer enters their credit card details on the form.
- The credit card details are sent to Stripe client-side and securely tokenized.
- If tokenization is successful (e.g. the card number is correct), the form is saved and a payment intent is created in Stripe server-side.
- If card authorization is required, it is shown the user.
- The card payment is confirmed and completed and the form is submitted.
- If the card payment is successful, the rest of the action configured on the form are run.
- If the card payment is not successful, an error is shown on the form.
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:
- Click WS Form in the WordPress administration menu.
- Click Settings.
- Click the Stripe Elements tab at the top of the page.
- Enter your license key.
- 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
Obtaining Stripe API Keys
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:
- Log in to your Stripe account.
- From your Dashboard, click Developers.
- Click API Keys.
Creating Restricted Keys
We recommend creating restricted keys for your Stripe integration having the following permissions.
All Core Resources
- Customers: Read / Write
- PaymentIntents: Read / Write
- SetupIntents: Read / Write
- Sources: Read
- Tokens: Read
All Billing Resources
- Invoices: Read
- Subscriptions: Write
Entering Your API Keys
To enter your publishable keys:
- Click WS Form in the WordPress administration menu.
- Click Settings.
- Click the Stripe Elements tab at the top of the page.
- Enter your test and live API keys.
- 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:
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, Subscription or Subscription – Custom Price
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:
- Log in to your Stripe Dashboard.
- Click on Products.
- Click on a product that contains a subscription (or create a new recurring payment product).
- Copy the API ID for the appropriate Price.
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 IDs, ensure you use IDs that relate to the current environment you are using.
- Edit the Stripe Card field in your form.
- Click the Add icon at the bottom right of the Subscription Price API ID(s) section.
- Paste the API ID into the setting and enter a quantity.
- 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:
- Log in to your Stripe Dashboard.
- Click on Products.
- Click on a product you wish to add (or create a new one-time payment product).
- Copy the API ID for the appropriate Price (It will begin with
price_).
To add the Price API ID in WS Form:
- Edit the Stripe Card field in your form.
- Click the Add icon at the bottom right of the Initial Invoice Item Price API ID(s) section.
- Paste the API ID into the setting and enter a quantity.
- Click the Save button at the bottom of the sidebar to save your changes.
You can add up to 10 items to this setting.
Subscription transactions with a custom price subscribe a customer to a Stripe Subscription whilst setting a custom price. The subscription must be set up in the Stripe Dashboard before it can be used. You can specify the interval and frequency of the subscription.
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.
Product API ID
You can find Product API IDs as follows:
- Log in to your Stripe Dashboard.
- Click on Products.
- Click on a subscription product you wish to use (or create a new subscription payment product).
- Copy the API ID for the appropriate Product (It will begin with
prod_).
Recurring Interval
Specifies billing frequency. Available options are:
- Day
- Week
- Month
- Year
Recurring Interval Count
This is the number of intervals between subscription billing.
For example, if:
- Recurring Interval: Month
- Recurring Interval Count: 3
… then Stripe will bill every 3 months.
You can enter a maximum of one year for the total interval (e.g. 1 year, 12 months, or 52 weeks).
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 (We recommend a minimum of first name, last name and email).
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.
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:
- Click the Add icon at the bottom right of the billing address mapping section.
- In the left-hand column, select a field from your form.
- In the right-hand column, select the corresponding Stripe billing address field.
- Repeat this process for each field on your form.
- 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:
- Click the Add icon at the bottom right of the shipping address mapping section.
- In the left-hand column, select a field from your form.
- In the right-hand column, select the corresponding Stripe shipping address field.
- Repeat this process for each field on your form.
- 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 / Variable | Additional 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. |