Stripe payments Inputfield for FormBuilder

The InputfieldFormBuilderStripe module provides a Stripe payment solution for ProcessWire FormBuilder, enabling you to collect credit card (and other) payments from Stripe with your form submissions. This module is included with FormBuilder.

Example of a Stripe card input element (screenshot):

• Requirements
• Installation
• Questions and answers
  • How can I make the payment optional?
  • How can I send receipts to customers for completed payments?
  • How can I receive emails for completed transactions?
  • How can I adjust the amount charged dynamically at runtime?
  • How can I change the way the credit card input is styled?
  • What if I need this module to do something it doesn't already do?
  • I want to have an online store or cart, how can I do that?
• Hooks
  • Hooks reference
  • Hook example

In addition to this Stripe input, FormBuilder also includes a Stripe Payments Processor that integrates Stripe Checkout.

Requirements

• FormBuilder 0.3.8 or newer is required.
• ProcessWire 3.0.123 or newer is recommend.
• You must have a Stripe account ready to receive payments.
• SSL certificate (HTTPS) is required once using Stripe LIVE mode.

In addition to the above, you must have Stripe API keys. These appear in your Stripe account as "Publishable" and "Secret" API keys, which you will enter in the module settings. I recommend entering both the TEST and LIVE versions of these API keys that Stripe provides. Using the TEST API keys enables you to thoroughly test the transactions without actually charging any money. In addition, the TEST API keys do not require HTTPS, which is useful during development on your own computer.

Installation

Before proceeding with installation, please make sure you've met all of the requirements in the previous section.

1. Copy these module files to your ProcessWire installation in the following directory: /site/modules/InputfieldFormBuilderStripe/

2. Install the module from your ProcessWire admin. You can find this by navigating to: Modules > Site > Inputfield > Stripe Payments for FormBuilder > Install.

3. The module configuration will ask you for your Stripe API keys. Populate them now and save. You can find these API keys in your Stripe account. Do not modify the "Stripe card elements styles" setting right now. You may return to that setting later if you need to change it.

4. Go to the FormBuilder module settings (Modules > Site > Form > FormBuilder) and scroll to the "Form and Field settings" field for "Allowed Input Types". Make sure that "FormBuilderStripe" is checked, and Save.

5. Go into FormBuilder (Setup > Forms) and edit an existing form or create a new one. Add a new field named "stripe_payment" or whatever you would like to name it. For the type, select "Stripe payments for FormBuilder".

6. When editing your new "stripe_payment" field, click on the "Details" tab and complete all of the settings. Instructions are provided inline for each, please be sure to read them in detail. Save your changes. In addition, unless you plan on making the payment optional, you should check the box on the "Basics" tab for "Required". If you need payment to be optional leave the box unchecked and see the FAQ further down.

7. Test your form and payment. When ready to go live, you should edit the Stripe field again and change the "Stripe charge mode" to LIVE. After going live, you should also test it once again with a real charge, and refund the amount back to yourself if you'd like, from the Stripe website. Please note that in order to use LIVE mode, your form must be on HTTPS.

8. Please make sure that you see your payments appear in your Stripe control panel, both TEST mode and LIVE mode. Do not assume it is working until you confirm it yourself.

Questions and answers

How can I make the payment optional?

To make the payment optional, make sure that the "required" checkbox is not checked in your Stripe payment field settings. Even after doing that, the field will behave as if it is required, at least on the Javascript side. This is just the way that Stripe Elements works. However, we've built in ak way that you can bypass that. To do so, create a new checkbox field above it, name it something like pay_now, and give it a label like "Pay now?".

Now edit your stripe_payment field and locate the "Show this field only if?" field in the "Visibility" fieldset on the "Basics" tab. In the value, enter the selector "pay_now=1". This will make the stripe_payment field appear only if the pay_now checkbox is checked. When the stripe_payment field is not visible, it is not required.

How can I send receipts to customers for completed payments?

This is handled in the Stripe control panel. When logged in to Stripe, navigate to Settings > Email Receipts, and check the appropriate boxes.

How can I receive emails for completed transactions?

When editing your form in FormBuilder, on the "Actions" tab you'll want to check the box to "Send email to administrator". Make sure your email is present there. You will receive a summary of the transaction.

In addition, Stripe can send you email notifications as well. Login to your Stripe account and click your name/avatar that appears in the supper right corner, and select "Profile". Navigate to the "Notifications" section in your profile and check boxes for all of the email notifications you want to receive.

How can I adjust the amount charged dynamically at runtime?

This module requires you to specify a fixed amount in the field settings. However, there may be conditions at runtime that affect the amount you want to charge. Things like shipping, quantities, etc. You can adjust the amount charged using a ProcessWire hook in your /site/ready.php file. See the hook example at the end of this page.

How can I change the way the credit card input is styled?

The credit card input is actually delivered through an iframe provided directly by Stripe. They let you adjust the styles of it by passing a JSON string of styles. We have made this JSON string editable in the InputfieldFormBuilderStripe module settings, and additional instructions are provided there as well.

What if I need this module to do something it doesn't already do?

Please post a feature request in the FormBuilder support board. If the feature is something that would be beneficial for most users, we may be able to add it. If the feature is something specific to your need, we may also be available for hire to create a custom version for you. Please contact us for additional info.

I want to have an online store or cart, how can I do that?

Payments through FormBuilder are for simple payment needs that cross-over with an intake form. But if you are wanting to run an actual online store or need a cart, plan to charge shipping, taxes, etc., your best bet is a dedicated store module for ProcessWire called PadLoper.

Hooks

Hooks reference

Following are hooks for the InputfieldFormBuilderStripe module. You may hook any one of these methods in the same manner as the example that appears at the end of this section.

getChargeAmount(InputfieldForm $form, FormBuilderProcessor $processor)

• Get amount to charge (in currency lowest unit).
• Useful to hook AFTER to dynamically adjust charge amount.
• Returns integer.

charge($token, $amount)

• Uses the Stripe API to charges the card for the given $amount.
• Useful to hook AFTER if you want to obtain the Stripe Charge object.
• Returns \Stripe\ApiResource instance (\Stripe\Charge).

chargeReady(InputfieldForm $form, $amount, array $data)

• Useful to hook if you want to perform some action before charge.
• Note the $data array argument contains 'processor' and 'token'.
• There is no return value.

chargeSuccess(InputfieldForm $form, $amount, $charge, array $data)

• Called after a card has been successfully charged.
• Useful to hook AFTER if you want to adjust what is stored for the transaction in the FormBuilder entry (by modifying $event->return).
• Note the $charge argument is a \Stripe\Charge object.
• Note the $data array argument contains 'processor' and 'token'.
• The return value is an array or string and it is the value that will be stored with the transaction in the FormBuilder entry.

chargeFail(InputfieldForm $form, $amount, $error, array $data)

• Called when a charge failed.
• Note that $error is the error message (string).
• Note the $data array argument contains 'processor' and 'token'.
• There is no return value.

formatAmount($amount, $currency = '')

• This is called when rendering a user-readable version of amount. For instance, it would format amount 500 as "$5.00 USD".
• Useful if you want to change the way the amount is formatted.
• Returns a string represented the formatted amount charged.

Hook example

Dynamic charge amount. Let's say that we have a "quantity" (integer) field in our form, and we want to multiply the default charge amount by the user entered quantity in order to come up with the total amount to charge. We would place this hook in our /site/ready.php file:

$forms->addHookAfter('InputfieldFormBuilderStripe::getChargeAmount', function($event) {
   $amount = $event->return; // charge amount for 1 item
   $form = $event->arguments(0); // InputfieldForm object

   // if the form is not the one you intend, exit now
   if($form->name != 'your_form_name') return;

   // get the quantity field
   $field = $form->getChildByName('quantity');

   // determine new amount and populate back to return value
   $quantity = $field->attr('value');
   $event->return = $amount * $quantity;
 }); 

See also: Stripe Payments Processor for FormBuilder