ConvesioPayPRO

The ConvesioPay 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 ConvesioPay payment process works as follows:

1. Customer enters their credit card details on the form.
2. The credit card details are sent to ConvesioPay client-side and are securely tokenized.
3. If tokenization is successful (e.g. the card number is correct), the form is submitted.
4. A payment is created server-side using the token.
5. If the card payment is successful, the rest of the action configured on the form are run.
6. If the card payment is not successful, an error is shown on the form.

Installation

The WS Form ConvesioPay 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 ConvesioPay 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 ConvesioPay 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 ConvesioPay

Obtaining ConvesioPay API Keys

In order to use the ConvesioPay fields on your form, you first need to enter your ConvesioPay keys.

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

To obtain your API keys:

1. Log in to your ConvesioPay account.
2. From your Dashboard, click Advanced Settings.
3. Under Checkout API Settings, there are three keys you will need to obtain:
   1. API Key (Click: Get Your API Key).
   2. Secret Key (Click: Generate a Secret Key).
   3. Client Key (Click: Generate Client Keys).

Each account in ConvesioPay is either a test or live environment. Ensure you set the Environment setting to match the environment you currently want to use when submitting your form.

Entering Your API Keys

To enter your publishable keys:

1. Click WS Form in the WordPress administration menu.
2. Click Settings.
3. Click the ConvesioPay tab at the top of the page.
4. Enter your test or live keys.
5. Click the Save button.

Configuring the Webhook

The webhook accepts requests from ConvesioPay to update transaction information such as the status (e.g. if a completed transaction is refunded).

To set up the webhook:

1. Click WS Form in the WordPress administration menu.
2. Click Settings.
3. Click the ConvesioPay tab at the top of the page.
4. You will see four webhook values:
   1. Webhook Name
   2. Webhook Integration Name
   3. Webhook Signature
   4. Webhook URL
5. Keeping the WS Form settings page open, open a new tab and go to your ConvesioPay dashboard.
6. Click on Advanced Settings.
7. Under Checkout API Settings, click on Register Webhooks.
8. Copy and paste the four settings above into the Register Webhooks fields.
9. Click Register Webhook.

Adding The ConvesioPay Fields

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

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

You can place the ConvesioPay and ConvesioPay Submit fields anywhere you like on the form.

Settings

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

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

The ConvesioPay 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 ConvesioPay 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.

Currency

ConvesioPay currently supports US Dollars.

Payment Reference

Enter a payment reference for the transaction. This defaults to WSF-#submit_id.

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.

The description is shown in a single line item for the transaction.

Customer

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.

Pass User to Component

If checked, WS Form will use the currently logged in users email address to identify the custom completing the payment form. This allows ConvesioPay to show stored payment methods on the form.

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

Language

Choose a language to display the credit card form in. Choose Auto Detect to use the browser locale.

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

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 ConvesioPay 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 ConvesioPay add-on introduces additional variables that you can use in actions such as messages and emails.