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. Stripe payment forms support Secure 3D payments with Strong Customer Authentication.

Download and install

1. This plugin requires Formidable Forms Pro. If you haven't already done so, install and activate Formidable Forms Pro.
2. 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.

1. Go to the Formidable → Global settings → Stripe tab, and add your API keys.
   
   Your keys can be found on your Stripe Account → Developers → API Keys page.
   
2. 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 → Developers → Webhooks page, and click the +Add endpoint button.
   
3. In the Endpoint URL field, 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

   

4. Choose the Latest API version.
5. You can either choose to receive all events or if you want the necessary events only, you would need to select at least the following:
   • All the charge.* events (except charge.dispute.)
   • checkout.session.completed
   • All the customer.* events
   • All the invoice.* events
   • All the order.* events
   • All the plan.* events
   • All the product.* events
   • All the source.*

Note: The Stripe add-on currently uses Stripe.js v3 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.

1. Go into edit the form you would like to use with Stripe. Click on Settings → Actions & Notifications → Collect a Payment.
   
2. Give your Payment action an Action Name for easy reference. This name will only be seen on the back-end.
   
3. 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 the icon in the Description box and then select your field in the modal box. This will insert a value like [3130] for your Description setting.
4. 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 the icon in the amount box and then click your field in the modal box. 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.

5. 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 one.
   
6. 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:
   

7. Would you like the Capture the Payment later? You can authorize the payment now, and manually collect it later. Or finalize and collect the payment when the entry is submitted.
8. Set your preferred currency for Stripe. By default, this will be set to U.S. Dollar (USD).
9. The Customer Information 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.
10. 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. Email notifications, Twilio (text messages), and MailChimp actions are currently setup to work this way. In each of these actions, you'll find 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='-7 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.

1. Go to the Formidable → Global settings → Stripe tab.
2. Select the option to Use the Stripe test mode. Make sure you have a valid Test Secret Key and Test Publishable Key entered. Hit Update.
3. Open the page where your Stripe form is published.
4. Submit a test entry. Use 4242424242424242 for the credit card number. Enter at least 50 cents for the amount.
5. 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.

1. Go into a form that has a Stripe action included.
2. Add a hidden field and Name it 'Payment status'.
3. Go into your form's Settings → Actions & Notifications and open the Stripe form action.
4. Scroll down to the After Payment section. Click the Add button.
   
5. 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.
   
6. 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.

1. 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.
2. Go to your form Settings → Actions & Notifications. Click Collect a Payment.
   
3. Rename the label to 'Basic Plan' and select your preferred payment type, if it is a one-time payment or recurring.
   
4. Select Add Conditional Logic. In this example, you would set 'Payment Plan' is equal to 'Basic'.
   
5. Click the Update button to save the form action.
6. Now, users who selected the 'Basic' payment plan will only be charged for the amount relevant to their chosen payment option.
7. Repeat steps 2-5 to create the form actions for the other payment plans.
8. To be sure that the one-time payment is processed, go to the Formidable → Global settings → Stripe tab, and select After entry is created.
   
9. Click the Update button to save the Stripe settings.

Need to conditionally collect payments through Stripe and PayPal in the same form? See how to add optional online payment processing to WordPress Forms.

Set up a recurring payment

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

1. Set up your WordPress form to take Stripe payments.
2. Under Payment type select 'Recurring'.
3. In the Repeat Every section, select how often the payment will recur.
   
4. 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.
   
5. 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.

1. Go to Settings → Actions & Notifications. Click Collect a Payment to add a Stripe form action.
   
2. In the Action Name box, insert 'Collect a Payment'.
3. In the Amount box, type in the amount of the non-recurring payment or use a field from your form to calculate the amount.
   
4. In the Payment Type, select 'One-time Payment'.
5. In the Actions & Notifications, add another Collect a Payment form action.
   
6. In the Action Name box, insert 'Collect a Payment with trial'.
7. In the Amount box, type in the amount of the recurring payment or use a field from your form to calculate the amount.
   
8. In the Payment Type, select 'Recurring'.
9. 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.
   
10. In the Actions & Notifications, add another Collect a Payment form action.
    
11. In the Action Name box, insert 'Collect a Recurring Payment'.
12. In the Amount box, type in the amount of the recurring payment or use a field from your form to calculate the amount.
    
13. In the Payment Type, select 'Recurring'.
14. In the Repeat Every section, select how often the recurring payment will take place.
    
15. Click Update. When the user submits the form, all form actions will be triggered for each type of payment.

Set up Authorize and Capture

Stripe has a two-step payment process which allows you to authorize a payment then capture it later. One of the benefits of using this feature is that you can capture the cardholder's payment only after an order or item is ready. This can help in reducing processing fees if there is a chargeback or refund. To get started, follow the steps below:

1. Open the form action settings to create a Stripe payment. Change Capture Payment to Later (collect manually).
2. Go to Formidable → Payments. When a payment is authorized but not captured, the status will be displayed as Authorized.
   
3. Select the payment to manually capture and click Capture now.
   
4. If the payment was successfully captured, the payment status will change to Completed. If the payment is not captured within 7 days, the authorization will expire and the funds will be released

Process refunds

Once you have received a payment, refunding said amount can be quickly done with the Stripe add-on.

1. To do this, navigate to Formidable → Payments. Hover over the Receipt ID for the payment you want to refund and click on View.
   
2. Inside this page, you can see several bits of information, but what we are looking for is located on the top right corner of your screen, the 'Payment Details' widget.
   
3. Click on Refund and click Yes in the confirmation box that shows up. If everything works as expected, the word Refunded should appear where the Refund button used to be.
   

Export list of payments

If you would like a compiled list of all the payments made in your Stripe form, you can export the entries as a CSV file. This will include the payment details and status.

To get started, navigate to the Formidable → Entries page and select the form where the Stripe payments were made. Then click the Download CSV button above the entries table to export the payment details via CSV.

Show a list of subscriptions

As an admin, you can see all the subscriptions on the Formidable → Payments → Subscriptions page.

Each subscription can be canceled from here as well.

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.

1. Set up your form to take a Stripe payment.
2. Add a Create posts action.
3. Add a post status field to your form, if you don't have one already.
4. 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'.
5. Click Update.
6. 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.
   
7. 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, check each of the following:

1. Do you have a credit card field in your form? If not, this is required in order for a payment to process.
2. Is your API key correct? Please review the steps above to make sure your API keys are setup and saved accurately.
3. Do you have more than one payment form on the same page? This is a current limitation of the Stripe add-on that we plan to improve in the future.
4. Are Formidable Forms and Formidable Forms Pro up to date? If not, please update.
5. Do you have another plugin installed that uses Stripe? If so, try deactivating it to check for a conflict.
6. Do you have the Formidable Authorize.net plugin installed? If so, you'll need to choose between the two. They are currently not designed to work together.

If you continue getting this message, please create a new ticket in the help desk.

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.

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.

If this error continues, the customer id assigned to the user can be manually deleted in PHPMyAdmin or with a line of code.

$user_id = 1; // Change the user id to the user getting errors.
delete_user_meta( $user_id, '_frmstrp_customer_id' );
delete_user_meta( $user_id, '_frmstrp_customer_id_test' );

Incomplete payments

When a form is loaded, an incomplete payment is created in Stripe. As the form is filled out, the value of the payment is updated.

If you would like to disable these incomplete payments in Stripe for $1 (or another currency), go to Formidable → Global Settings → Stripe. Set the option to Process One-time Payments to After entry is created.

Payment Intent status: requires_payment_method

If you are seeing this error in the Stripe logs, then it is possible that the automatically generated "Payment Method" field has been deleted or otherwise modified. This field is hidden, but required for Stripe to process the payment. If you don't see the field in your form, delete the credit card field and the Stripe form action, and then re-create them. If the field is present, make sure there is no conditional logic set on this field.

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.

In addition to the log stored in Formidable, Stripe has a separate log. It may be useful to compare the two and see if additional errors are appearing in your Stripe account log as well. You can find it in your Stripe dashboard under Developers → Logs.

Actions not triggering on Successful payment

If you are getting "No such plan" errors or "Successful payment" and other payment form action triggers are not working properly, your Stripe webhook may not be set up properly. Review steps 2-5 and make sure that the URL is correct for Formidable Stripe.

No payments created

If no payments are showing up under your Formidable → Payments page, it's possible that your database has not created a Payments table or is not properly updating. On some servers, the database user doesn't have permissions to ALTER database tables. To grant and revoke rights to database tables using phpMyAdmin, follow the instructions below:

1. Navigate to the Privileges tab which has a list of your users.
2. Click the Edit Privileges link.
3. Select your database.
4. In the Database-specific privileges, select the wp_frm_payments table.
5. In the Table-specific privileges, you can define the operations in detail.
6. Manually make adjustments to the table to match the structure in our database schema.

Note: If you are using the PayPal add-on at the same time, leave the Completed column as is.

Cannot set id on this object

If you see the error message Cannot set id on this object. HINT: you can't set: id, check each of the following:

1. Do you see anything related to this error in the Stripe logs?
2. Do you have another plugin installed that uses Stripe? Try deactivating it to check for a conflict.

If you continue getting this message, please create a new ticket in the help desk.

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 );
  }
}

Trigger an action based on payment amount

If you want to trigger an action in another form (or the same form) when a payment is more than a certain amount, use the following example:

add_action( 'frm_payment_status_complete', 'frm_trigger_action_on_payment' );
function frm_trigger_action_on_payment( $atts ) {
  $payment_amount = $atts['payment']->amount;

  if( $payment_amount < 100.00 ) { // Change 100.00 to the payment amount above which you want to trigger the action
	return;
  }
  
  $entry_id = isset( $atts['entry'] ) ? $atts['entry'] : $atts['payment']->item_id;
  $entry = FrmEntry::getOne( $entry_id, true );
  $form = FrmForm::getOne( $entry->form_id );
  FrmFormActionsController::trigger_actions('update', $form, $entry, 'email');
}

As is, the above example will trigger all Email actions set to trigger on update, in the same form. If you want to trigger an action in a different form, change $entry_id to the entry ID of an entry in another form.

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;
}

Get customer ID

You can find the Stripe customer ID in the user meta called _frmstrp_customer_id or _frmstrp_customer_id_test. To get the customer ID, use this line of code:

get_user_meta( get_current_user_id(), ' _frmstrp_customer_id' )