Stripe Forms

Knowledge Base → Add-Ons → eCommerce → Stripe Forms

Integrate your WordPress forms with Stripe to process your one-time and recurring payments. Stripe forms enhance the user experience by allowing users to stay on your site while securely making a payment.

In order to use Stripe forms, you will need an SSL connection. However, you can use an unencrypted connection for testing purposes.

Download and install

This plugin requires Formidable Forms Pro. If you haven't already done so, install and activate Formidable Forms Pro.
In your WordPress admin, go to 'Formidable' → 'Add-Ons' and click the 'Install' button for the WordPress Stripe plugin.

Set up Stripe API integration

Now that the Stripe Forms plugin is activated you'll need to connect your Stripe account. To do this follow the steps below.

Go to the Formidable → Global settings → Stripe tab, and add your API keys.

Your keys can be found on your Stripe Account → API Keys page.
If you would like to use recurring subscriptions or refund payments from stripe.com, your site will need to receive notifications from Stripe. To enable these notifications, go to your Stripe Account → Webhooks page, and add the link shown at the bottom of your Formidable → Global settings → Stripe tab. The link will look like this:
```
https://example.com/wp-admin/admin-ajax.php?action=frm_strp_event
```

Note: The Stripe add-on currently uses Stripe.js v2 for processing payments.

Set up a Stripe form to collect payments

Once you have the Stripe plugin activated and have connected your Stripe account, you can set up a form to take Stripe payments. Follow the directions below to collect Stripe payments with a Formidable form.

Go into edit the form you would like to use with Stripe. Click on "Settings" → "Form Actions" → "Collect a Payment".
Give your Payment action a Label for easy reference. This label will only be seen on the back-end.
Give your Payment action a Description to attach to the payment. This information will be sent to Stripe along with the payment. You can either type in a description, or use a field from your form to set the description dynamically. If you would like to use a field for the description, click into the Description box and then click your field in the right sidebar. This will insert a value like [3130] for your Description setting.
Set the Amount for the payment. You can either type in an amount, or use a field from your form to calculate the amount. If you would like to use a field for the amount, click into the amount box and then click your field in the right sidebar. This will insert a value like [3138] for your Amount setting.

It may be helpful to use field calculations to calculate a total in your form.

Note: If you are using a field that uses separate values in the Amount field, insert [x show=value] instead of [x], where x is the field ID.
Next, make sure you have a Credit Card field in your form so that Stripe can process payment. If you do not have a Credit Card field in your form, you will be reminded to add a credit card field to your form.
Your Payment Type can be one-time or recurring. You can add multiple actions to your form if you would like both one-time and recurring payments. If you would like to allow either a one-time payment or recurring subscription, be sure to add conditional logic to both actions so they will only trigger at the times you would like.
If you have chosen a recurring payment type, you will see the following options:
Set your preferred currency for Stripe. By default, this will be set to U.S. Dollar (USD).
Your Customer Info fields can be associated with field values in your form.

If you would like to pass a custom address to Stripe, you will need to add an Address field to your form.
You can also change field values automatically when a payment is completed, fails, or is refunded. Anything you set here will be also be triggered with every payment in a subscription.

For example, if you are creating posts, and would only like the post published when it is paid, use the After Payment settings. When the Payment is Completed, set your post status field to "publish". When Failed, set it back to "draft."

Note: When you add or save Stripe settings, a field called 'Payment method' is added automatically. This field is required. Do not remove it or your payments will not be sent to Stripe for processing.

Trigger Actions after Payment

There are several actions that can be triggered after a payment is complete or fails. Emails, Twilio (text messages), and MailChimp actions are currently setup to work this way. In each of these actions, you'll find now options in the "Trigger this action after ____" setting. If you would like an email to be sent after the payment is complete, uncheck "Create" and check "Successful Payment."

With recurring payments, each payment will trigger one of these actions ("Successful Payment" or "Failed Payment"). The "Failed Payment" event occurs when a payment that is part of a recurring subscription fails.

To customize the subscription renewal email, inline conditional statements can be used. In this case, if the entry was created more than 14 days ago, the email content can be different.

[if created_at less_then='-14 days']This is a renewal payment[/if created_at]

Run a test payment

It's often helpful to run test payments to make sure your form and Stripe are functioning well. Follow the steps below to run a test payment.

Go to the Formidable → Global settings → Stripe tab.
Select the 'Use the Stripe test mode' option. Make sure you have a valid Test Secret Key and Test Publishable Key entered. Hit 'Update Options'.
Open the page where your Stripe form is published.
Submit a test entry. Use 4242424242424242 for the credit card number. Enter at least 50 cents for the amount.
That's it! The form should submit normally if it is configured well and there are no errors.

Save payment status in a field

If you would like to save the status of a payment in a field in your form, follow the instructions below.

Go into a form that has a Stripe action included.
Add a hidden field and Name it 'Payment status'.
Go into your form's 'Settings' → 'Form Actions' and open the Stripe form action.
Scroll down to the After Payment section. Click the 'Add' button.
In the 'Payment Status' column, select 'Completed'. In the 'Field' column, select your 'Payment status' field. In the Value column, select 'Completed'. You can do the same for the 'Refunded' and 'Canceled' payment status.
Hit Update. When a form payment is successfully completed, the payment status field will switch to 'Completed' to reflect the status of the Stripe payment. If the payment status is not updating properly, please make sure that your API keys are set up and saved accurately.

Conditionally collect payments

If you would like to set up different payment options in your form using Stripe, you'll need Conditional Logic. Suppose you have three payment plans in your form: Basic, Pro, and Enterprise.

In your form, add a 'Dropdown', 'Radio', or 'Checkboxes' field called 'Payment Plan'. For this example, you would add the options: 'Basic', 'Pro', and 'Enterprise'. When your users fill out the form, they will select the payment plan that they would like to avail.
Go to your form → 'Settings' → 'Form Actions'. Click the Collect a Payment icon.
Rename the label to 'Basic Plan' and select your preferred payment type, if it is a one-time payment or recurring.
Select 'Use Conditional Logic'. In this example, you would set 'Payment Plan' is equal to 'Basic'.
Click the 'Update' button to save the form action.
Now, users who selected the 'Basic' payment plan will only be charged for the amount relevant to their chosen payment option.
Repeat steps 2-5 to create the form actions for the other payment plans.

Set up a recurring payment

If you would like to set up a Stripe form action to take recurring payments, follow the steps below:

Set up your WordPress form to take Stripe payments.
Under Payment type select 'Recurring'.
In the Repeat Every section, select how often the payment will recur.
You may include a trial period before the actual subscription begins. If you would like to include a trial period, select how long the 'Trial Period' will be.
Click Update. Now when a user submits the form, Stripe will automatically bill the user at intervals determined by your 'Repeat Every' setting.

Set up multiple types of payment

With Stripe, any number of payment options can be triggered on single form submission. Here's an example of how you can allow multiple payments such as one-time (non-recurring) payment, payment with a trial, and recurring payment. All of these form actions should trigger upon form submission.

Go to 'Settings' → 'Form Actions'. Click the 'Collect a Payment' icon to add a Stripe form action.
In the Label box, insert 'Collect a Payment'.
In the Amount section, select 'Set Amount'. In the box, type in the amount of the non-recurring payment or use a field from your form to calculate the amount.
In the Payment Type, select 'One-time Payment'
In the 'Form Actions', add another 'Collect a Payment' form action.
In the Label box, insert 'Collect a Payment with trial'.
In the Amount section, select 'Set Amount'. In the box, type in the amount of the recurring payment or use a field from your form to calculate the amount.
In the Payment Type, select 'Recurring'.
In the Repeat Every section, select how often the recurring payment will take place. In the Trial Period section, select how long the 'Trial Period' will take place.
In the 'Form Actions', add another 'Collect a Payment' form action.
In the Label box, insert 'Collect a Recurring Payment'.
In the Amount section, select 'Set Amount'. In the box, type in the amount of the recurring payment or use a field from your form to calculate the amount.
In the Payment Type, select 'Recurring'.
In the Repeat Every section, select how often the recurring payment will take place.
Click Update. When the user submits the form, all form actions will be triggered for each type of payment.

Show a list of subscriptions

As an admin, you can see all the subscriptions on the Formidable -> Payments -> Subscriptions page.
Stripe List Subscriptions

Each subscription can be canceled from here as well.
Stripe View Subscription

Show subscriptions for current user

If you would like to show your users a list of their subscriptions, along with cancellation links, insert [frm-subscriptions] on a page. If a user is logged in, they will see their subscriptions listed here.

Get receipt ID

If you would like to get the receipt ID for a specific entry, you may use this shortcode:

[frm-receipt-id entry="[id]"]

This shortcode may be placed in a View, email message, success message, or even an API action that fires after a payment is complete.

Publish a post on complete payment

If you would like to publish a post after collecting a Stripe form payment, follow the steps below.

Set up your form to take a Stripe payment.
Add a Create posts action.
Add a post status field to your form, if you don't have one already.
Select 'Draft' as the default value in your new 'Status' field.

If you do not want the user to have access to changing the status of this field, you can set the field to Read Only. You can also hide the whole field from the user by changing the Visibility to 'Administrator'.
Click Update.
Go into the form's Stripe action. In the After Payment section, set the dropdown in the Payment Status column to 'Completed', set the dropdown in the Field column to your 'Status' field, and type 'publish' in the Value column.
Click Update and Publish your form on a page. Now when a user submits the form with their payment information received, the post will be published.

Troubleshooting

The Stripe Token is missing.

If you see this error message appear, it may mean that you have not added a credit card field to your form which is required in order for payment to process.

It also may be due to an incorrect API key. Please review the steps above to make sure your API keys are setup and saved accurately. If you continue getting this message, please create a new ticket in the help desk.

This error message also shows if you have more than one payment form on the same page. This is a current limitation of the Stripe addon that we hope to improve in the future.

No such customer

When a logged in user submits a payment, a customer is created for that user in Stripe. The customer ID is linked to the logged in user. If the Stripe account is changed, or the customer account deleted in Stripe, a logged in user who has previously submitted a payment may see the message "No such customer" when a payment form is submitted. When this happens the customer ID is unlinked from the user, and the next try from this user should be successful. This message will not appear for logged out users or for those submitting the first payment. To avoid this issue, do not delete customers in Stripe.

No such plan

The Stripe form settings automatically create a plan in Stripe. However, if the Stripe account is changed, the plan will not exist in the new account. If you submit a payment form and see the 'No such plan' message, return to the Stripe payment settings for this form, and save the settings again. This will trigger the plan to be created in Stripe again. It may help to make a small change in these settings to ensure the plugin knows to create the plan.

Logging for other errors

A log file is stored inside of the Stripe plugin that keeps a list of the most recent errors. If you run into an error related to the payments and are not sure where to start, a log message would be helpful. The log can be located in wp-content/plugins/formidable-stripe/formidable-payments/log/results.log. The most recent messages are at the bottom of the log.

Additional Customizations

Change the user role

The only change needed in the example is the user role the user should have: $new_role = 'contributor';

Similar hooks are fired each time the status on payment changes. These hooks work exactly the same way but simply fire at different times.
frm_payment_status_complete
frm_payment_status_refunded
frm_payment_status_failed
frm_payment_status_canceled

Each of these functions include an array ($atts in the example below). This array includes the following parameters:

trigger (string) - the status of the payment
entry_id (int) - The ID of the entry linked to the payment
payment (object) - The payment information from the Formidable -> Payments page.
The payment object includes: receipt_id, invoice_id, sub_id, item_id, amount, status, action_id, paysys, created_at, begin_date, expire_date, and meta_value.

You may want to add another function to change the role back if a payment fails or is refunded. This example changes the user role when the payment is completed. With a recurring payment, this hook will be fired each time a payment is completed.

add_action( 'frm_payment_status_complete', 'frm_change_the_role' );
function frm_change_the_role( $atts ) {
  $new_role = 'contributor';
  $entry = isset( $atts['entry'] ) ? $atts['entry'] : $atts['payment']->item_id;
  if ( is_numeric( $entry ) ) {
    $entry = FrmEntry::getOne( $entry );
  }

  $user_id = $entry->user_id;
  if ( ! empty( $user_id ) ) {
    $user = get_userdata($user_id);
    if ( ! $user ) {
        return; //don't continue if user doesn't exist
    }

    $updated_user = (array) $user;

    // Get the highest/primary role for this user  
    $user_roles = $user->roles;
    $user_role = array_shift( $user_roles );
    if ( $user_role == 'administrator' ) {
        return; //make sure we don't downgrade any admins
    }

    $updated_user['role'] = $new_role;
	
    wp_update_user( $updated_user );
  }
}

Only authorize payments

This example will help you authorize a payment, but collect it later. In order to collect/capture the payment, you'll need to log into your Stripe account and use the options there.

add_filter( 'frm_strp_new_charge', 'set_stripe_to_auth_only' );
function set_stripe_to_auth_only( $new_charge ) {
  $new_charge['capture'] = false;
  return $new_charge;
}

Use the Stripe receipt

By default, an email form action can be used to send a receipt. In this case, the email would be set to trigger after successful payment. But this example will allow you to use the Stripe receipts.

add_filter( 'frm_strp_new_charge', 'set_stripe_to_trigger_receipt', 10, 2 );
function set_stripe_to_trigger_receipt( $new_charge, $atts ) {
  if ( $atts['action']->ID == 30 ) { // change 30 to your payment form action ID
    $email_field_id = 25; // change 25 to your email field id
    $new_charge['receipt_email'] = $atts['entry']->metas[ $email_field_id ];
  }
  return $new_charge;
}