How to Use the Payment Form Block

Reading time: 4 minutes | Difficulty: Beginner

Overview

The WP Simple Pay – Payment Form block is the recommended way to insert a payment form into a Gutenberg post or page. It provides a live preview of the form inside the editor, exposes display options in the block sidebar, and renders the same on-page form a customer would see — without you ever needing to copy a shortcode.

The block is functionally equivalent to the shortcode but is more discoverable and provides editor previews that reflect the form’s current Form Style settings.

Prerequisites

• WP Simple Pay (any tier — the block ships with the free plugin)
• A WordPress site running the block editor (Gutenberg)
• At least one published payment form

Step 1: Insert the Block

1. Edit the post or page where you want the form to appear.
2. Click the + block inserter.
3. Search for WP Simple Pay or Payment Form.
4. Click the WP Simple Pay – Payment Form block.

A placeholder appears prompting you to select a form.

Step 2: Choose a Form

Use the dropdown in the block placeholder to pick which published payment form to render. Once selected, the block replaces the placeholder with a live preview of the form, including title, description, fields, and the submit button — styled with the form’s current Form Style settings.

If you change a form’s Form Style after inserting the block, the preview updates the next time you reload the editor.

Step 3: Configure Display Options

With the block selected, the right-hand block settings sidebar exposes two toggles:

• Show Title — When enabled (default), displays the form’s title above the fields. Disable to hide the title — useful when the surrounding page already has a heading.
• Show Description — When enabled (default), displays the form’s description text above the fields. Disable for compact layouts.

If you disable both, the title/description wrapper is suppressed entirely so there’s no leftover whitespace.

The block also supports Center Alignment via the standard block toolbar. When centered, the form, embedded heading, and submit button are horizontally centered within the page’s content width and the heading area is constrained to a 400px max-width.

Step 4: Publish and Preview

Save or publish the page. View it on the frontend to see the form in its rendered state. The block uses the same rendering pipeline as the shortcode, so behavior on the frontend is identical.

Block vs Shortcode

	Block	Shortcode
Editor preview	Live, styled	None — placeholder only
Display toggles	UI checkboxes	Manually edit shortcode attributes
Alignment	Block toolbar	Wrap in HTML/CSS
Works in classic editor	No	Yes
Works in widgets	Yes (block widgets)	Yes
Works in page builders	Depends on builder	Yes (universal)

When to use the block: Modern Gutenberg posts and pages, FSE templates, block-based widgets.

When to use the shortcode: Classic editor, page builders without first-party block support, custom theme templates where you call do_shortcode() directly.

Frequently Asked Questions

The form preview shows but customers can’t pay — why?

The block renders the same form for the editor preview as it does for visitors. If the preview shows the form but submissions fail, the issue is with the form configuration itself (missing payment method, invalid Stripe keys, missing required field) rather than the block. Check WP Simple Pay > Payment Forms and the form’s General/Payment tabs.

Can I use multiple Payment Form blocks on the same page?

Yes — each block can render a different form. The plugin’s frontend assets are smart enough to handle multiple forms on the same page without conflict.

Why doesn’t the editor preview match what I see on the frontend?

The editor preview reflects the form’s saved state at the moment the editor loaded. If you’ve made changes to the form in another tab, save/refresh the editor to see them. The frontend always renders the latest saved version.

Does the block work in Full Site Editing (FSE) templates?

Yes. The block can be inserted into any block-aware context, including FSE templates, template parts, and reusable blocks/patterns.

Can I style the embedded form independently per page?

Form Style is per-form, not per-block. To use different styles on different pages, create multiple forms and insert the appropriate block on each page.

What’s the difference between this and the WP Simple Pay Button block?

The Payment Form block embeds the entire form inline. The Button block displays just a button that opens the form in an overlay (modal) when clicked — useful for landing pages where you want a clean call-to-action rather than a visible form. See How to Use the Payment Button Block.

What’s Next?

• How to Style Your Payment Forms with Form Style – Customize how the embedded form looks
• How to Use the Manage Subscriptions Block – Let subscribers manage their plans
• How to Configure a Payment Form’s General Settings – Configure the form itself