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

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

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 a Label for easy reference. This label 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 a credit card field to your form.
   
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. Set your preferred currency for Stripe. By default, this will be set to U.S. Dollar (USD).
   
8. 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.
9. 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.

1. Go to the Formidable → Global settings → Stripe tab.
2. 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'.
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 'Use 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.

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 Label box, insert 'Collect a Payment'.
   
3. 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.
   
4. In the Payment Type, select 'One-time Payment'
   
5. In the 'Actions & Notifications', add another 'Collect a Payment' form action.
   
6. In the Label box, insert 'Collect a Payment with trial'.
   
7. 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.
   
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 Label box, insert 'Collect a Recurring Payment'.
    
12. 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.
    
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. Add the custom code to authorize payments.
2. Go to Formidable → Payments. When a payment is authorized but not captured, the status will be displayed as Authorized.
   
3. Select the entry to manually capture the payment and click Capture now.
   
4. If the payment was successfully capture, you will notice that the payment status will be changed 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' → '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' on the alert 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. Do you have another plugin installed that uses Stripe? If so, try deactivating it to check for a conflict.

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

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.

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

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