PBJ Form Builder — User Guide

PBJ Form Builder — Install & Usage Guide

This is the user-facing guide. If you're a developer poking at the code, see pbj-form-builder-CODE-EXPLAINER.md.

1. Install

1. In WordPress admin, go to Plugins → Add New → Upload Plugin.
2. Upload pbj-form-builder.zip and click Install Now.
3. Click Activate Plugin.
4. You should now see a Form Builder menu item in the left sidebar.

2. Configure global settings

Go to Form Builder → Settings.

General

• Currency — three-letter ISO code (USD, EUR, GBP, AUD, etc.). Used by both gateways.
• Default success message (no payment) — shown after a successful free submission, when a form's own success message is blank.
• Default success message (paid) — same idea, but for paid submissions.
• Admin notification email — email address that gets a copy of every successful submission. Leave blank to disable. On paid submissions this email now also includes the Amount, Transaction ID, and Gateway, and the Reply-To is set to the buyer's email address so you can answer them directly.

Buyer receipts

• Receipt email — when enabled (the default), every paid submission emails the buyer a plain-text receipt: the form title, date, their answers, the amount, the transaction ID, and the gateway. Free submissions never send a receipt.
• Receipt subject — {form} is replaced with the form title (default: Receipt: {form}).
• Receipt "From" name — optional display name for the receipt email. Leave blank to use the site default. Replies to the receipt go to the Admin notification email when one is set.

The buyer's address is taken from the first Email-type field on the form (falling back to any submitted value that looks like an email). If the form has no email field, no receipt is sent.

Anti-bot

• CAPTCHA — enables the built-in math challenge.
• Honeypot — enables the hidden trap field.
• Minimum time on page before submit — seconds. The default of 2 catches most autosubmit scripts.
• Max submissions per IP per hour — 0 means unlimited.

Both CAPTCHA and Honeypot have global toggles here AND per-form toggles in the form editor. A feature has to be enabled at both levels to be active on a given form.

Behind Cloudflare or another reverse proxy? As of 1.2.0 the rate limiter only trusts the direct connection IP (REMOTE_ADDR) by default, because proxy headers are trivially spoofable. If your site sits behind Cloudflare (or a proxy you control that sets CF-Connecting-IP / X-Forwarded-For), add this one-liner to a small must-use plugin or your theme's functions.php so the limiter sees real visitor IPs instead of the proxy's:

add_filter( 'pbj_form_builder_trust_proxy_headers', '__return_true' );

Square

1. Tick Enable Square.
2. Pick Sandbox (for testing) or Production (for real payments).
3. Get your three keys from the Square Developer Dashboard:

• Application ID — under "Credentials"
• Location ID — under "Locations"
• Access token — under "Credentials" (use the right one for your environment)

1. Paste them in and Save.

Stripe

1. Tick Enable Stripe.
2. Get your two keys from the Stripe Dashboard → Developers → API keys:

• Publishable key — starts with pk_test_ or pk_live_
• Secret key — starts with sk_test_ or sk_live_

1. Paste them in and Save.

There is no environment dropdown for Stripe — test vs live mode is decided entirely by which keys you enter. Paste your pk_test_/sk_test_ pair to test, then swap in the pk_live_/sk_live_ pair to go live. Don't mix a test key with a live key.

Note: the Stripe integration charges cards directly (no redirect). Cards that require redirect-based 3-D Secure authentication are declined with a message asking the buyer to use a different card.

PayPal

1. Tick Enable PayPal.
2. Pick Sandbox or Production (Live).
3. Get your credentials from the PayPal Developer Dashboard:

• Client ID
• Client Secret

1. Paste them in and Save.

3. Build a form

1. Go to Form Builder → Add New.
2. Set a Form title (this becomes the form's name — visitors don't see it).
3. Set Status — Published or Draft. Only Published forms render via shortcode.
4. Description — optional paragraph shown above the fields.
5. Submit button label — defaults to "Submit".

Adding fields

Click Add field. For each field, set:

• Label — what the visitor sees.
• Field key — machine-readable name, used as the POST key. Auto-derived from the label if you leave it blank.
• Type — pick from Text, Email, Phone, URL, Number, Date, Paragraph, Dropdown, Radio, Checkboxes, Single consent checkbox, Hidden, or Custom (a free-form text input you can use for anything not covered by a standard type).
• Width — Full or Half. Two half-width fields next to each other become a two-column row on desktop; everything stacks on mobile.
• Required — toggle.
• Help / placeholder — shown inside the field on text inputs, under the field on choice inputs.
• Default value — pre-fills the field. For Hidden type, this IS the value that gets submitted.
• Options — for Dropdown / Radio / Checkboxes only. One per line, in the format:

  Label|value
  Another label|another_value

If you skip the |value part, the value is derived from the label.

Drag the menu handle (☰) at the top of each row to reorder.

Payment

• Payment gateway — None, Square, Stripe, or PayPal.
• Price — two-decimal amount, e.g. 25.00. Currency comes from Settings.

If you pick a gateway whose credentials aren't set in Settings, the form will fall back to a plain submit button (no payment) and the visitor won't be charged.

After submit

• Success message — shown in place of the form after a successful submit. Leave blank to use the site-wide default.
• Redirect URL — if set, the visitor is sent to this URL after submit instead of seeing the success message.

Anti-bot (per form)

• Show math CAPTCHA on this form — respects the global toggle.
• Include hidden honeypot bot trap — respects the global toggle.

Click Save form. You'll see the shortcode appear at the top of the edit page.

4. Place the form on a page

Copy the shortcode (e.g. [pbj_form id="42"]) and paste it into any post, page, widget, or block-editor Shortcode block. Save the page. That's it.

5. View submissions

Go to Form Builder → Submissions. You'll see every submission, newest first. Filter by form using the dropdown at the top.

Each row shows the date, form, a short summary of the first two non-hidden fields, the gateway used (if any), and the amount paid. Click View for the full field-by-field detail, IP address, and transaction ID.

Submissions are stored as a WordPress custom post type (pbj_form_entry). Deleting a form does NOT delete its submissions — they stick around so you can still see what came in. Deleting the plugin entirely (Plugins → Delete) wipes everything: settings, forms, submissions.

6. Test mode

All three gateways have a test mode. Use it.

• Square sandbox — use the Square test card numbers (e.g. 4111 1111 1111 1111, any future date, any CVV, any ZIP). The Square Web Payments SDK loads from sandbox.web.squarecdn.com automatically when you pick the Sandbox environment.
• Stripe test mode — enter your pk_test_/sk_test_ keys and use the Stripe test cards (e.g. 4242 4242 4242 4242, any future date, any CVC, any ZIP). No environment dropdown — the keys decide the mode.
• PayPal sandbox — log in with a sandbox personal account from your PayPal sandbox accounts.

For Square/PayPal, switch the environment dropdown back to Production and re-enter your live keys when you're ready to go live. For Stripe, just swap the test keys for the live ones.

Troubleshooting

"Security check failed" — the form's nonce expired. Refresh the page and submit again.

"CAPTCHA answer was incorrect" — either the answer was wrong or the form sat open for more than 30 minutes. Refresh and try again.

"Submission was too fast" — you submitted in under 2 seconds. Either your real users are unusually fast or a script is misbehaving — adjust the threshold under Settings → Anti-bot.

Square card field doesn't appear — make sure Square is enabled and the Application ID + Location ID are filled in. Open the browser console and look for errors.

Stripe card field doesn't appear — make sure Stripe is enabled and the Publishable key is filled in. Open the browser console and look for errors.

"This card requires additional authentication" — the buyer's bank demanded a redirect-based 3-D Secure challenge, which this integration deliberately disallows. The buyer should try a different card.

PayPal buttons don't appear — make sure PayPal is enabled and the Client ID is filled in. Sandbox and production use different client IDs — make sure you're using the right one for the environment you picked.

"Please complete the PayPal payment to submit this form" — you hit the submit button instead of the PayPal button. The submit button is hidden when PayPal is the gateway, but some themes restyle it back into view. The PayPal capture flow is the only way to complete a PayPal-funded submission.