Gravity Forms Square - WordPress Plugin

Guide to Setting Up Gravity Forms Square for WordPress Payment Forms

Gravity Forms Square does more than just add a payment field to a form. In a real project, it ties together three parts: the Gravity Forms form, the Square payment account, and the WordPress admin entry that the site owner later uses to check payment status, refunds, subscriptions, or delayed captures. This guide walks through the full workflow: preparing the site, connecting Square, building a compatible form, configuring the feed, testing in Sandbox, verifying the result, and troubleshooting common failures.

This guide is written for a WordPress administrator who already knows why they need a payment form but wants to avoid common mistakes: currency mismatches, a missing Square Field, the wrong Live or Sandbox mode, a non-functioning feed, an outdated Credit Card Field left in the form, or conflicts with the theme, cache, or page builder. It does not cover bypassing licensing, buying accounts, or manually handling bank card data. The focus here is strictly on safely configuring a product you already have.

Special attention is given to the less obvious mechanics of the plugin: how the payment amount is selected, why Square Field is different from the old Credit Card Field, when Authorize Only makes sense, how subscriptions work, what appears in Entry Detail, and why Sandbox needs to be tested differently from Live mode. After reading this guide, you should be able not only to install the integration, but also to pinpoint where to look if the form submits but the payment does not go through.

What the form and Square integration is meant to solve

Gravity Forms Square turns a standard WordPress form into a managed payment touchpoint. That is useful when a full online store would be excessive: booking a consultation with a deposit, event registration, course payments, one-time contributions, service requests, donations, paid content submissions, or a small set of products without a complex cart. The user stays on the form page, enters contact and payment details, and the administrator sees the result in the form entries.

The key term in Gravity Forms is the feed. It is the rule that tells the plugin what to do with the data after the form is submitted successfully. For Square, the feed is responsible for sending the amount, customer details, and transaction type to Square. Without a feed, the form may look correct, include a payment field, and even save an entry, but the payment flow will not be configured as a complete working chain.

For lightweight payment scenarios, this is often more practical than building a full product catalog. You can create a form with several service options, add name, email, and address fields, calculate the total with Pricing Fields, and immediately pass the payment to Square. At the same time, Gravity Forms remains in control of the form and its logic: conditional fields, notifications, confirmations, extra add-ons, and entries all continue to work inside the familiar WordPress admin interface.

It is important to understand the product boundary, though. Gravity Forms Square is not a replacement for inventory management, a complex storefront with a cart, multi-step store checkout, POS catalog sync, or advanced WooCommerce workflows. If the site sells dozens of products with stock levels, variations, coupons, shipping, and order management, WooCommerce with its Square integration is usually the more sensible direction. But if you need a managed payment step directly inside a form, with flexible questions before checkout, this add-on fits the job well.

Who this plugin fits and where it is the wrong tool

Gravity Forms Square is a strong fit for sites where payment is part of a request rather than a standalone shopping cart. For example, a studio taking a reservation deposit, a training center collecting payment for an intensive course, a nonprofit accepting donations, a coach selling membership plans, or an agency taking a prepayment for an audit. In scenarios like these, it matters more to tailor the form to the customer question than to build a full catalog of products.

The plugin is especially useful for teams already using Square for in-person sales or invoicing. In that case, the online form becomes just another payment channel rather than a separate ecosystem. The administrator does not have to make the customer wait for a manual payment link, and the team immediately sees the form entry, amount, contact information, and payment status.

Another strong use case is forms with conditions. Gravity Forms can display different fields, notifications, and feeds depending on the user’s answers. For payments, that means the same screen can handle different paths: one-time payment or request without payment, standard purchase or pay-after-approval, monthly donation or one-time contribution. The most practical value of Gravity Forms Square shows up when the payment decision depends on the form data.

The plugin may not be the right fit if you need dozens of payment methods, Apple Pay or Google Pay through Stripe, customer-managed subscriptions from an account area, complex tax and shipping rules, product sync with a POS, multilingual checkout with local payment methods, or large-scale eCommerce analytics. In those cases, it makes sense to compare Square Add-On with Stripe Add-On, PayPal Checkout, Square for WooCommerce, or purpose-built payment form platforms.

You should also review the Gravity Forms licensing requirements. The official integration page states that Square Add-On is available with Pro, Elite, and Nonprofit licenses. If the project runs on a Basic license or an unofficial build without access to official updates, do not treat the payment form as a mission-critical site component. For payments, updates, support, and compatibility with the current WordPress version matter.

What to check before installation

Before installing, do not start with the Install button. For a payment add-on, preparation matters more than it does for a regular form field. Environment problems do not always show up as clear error messages. Sometimes the form simply fails to display the card field, hangs on submit, returns a Square decline, or saves an entry without the expected payment status.

WordPress and Gravity Forms environment

Confirm that Gravity Forms itself is installed and that the server meets the current product system requirements. The official Gravity Forms documentation lists the minimum WordPress and PHP requirements, along with required PHP extensions including curl and openssl. For a payment integration, this is not a formality: the OAuth connection to Square, API requests, and secure data transfer all depend on correct server configuration.

In the admin area, open Forms and review the system status. If the site has not been updated in a long time, test updates on a copy of the site first. Do not update WordPress core, Gravity Forms, the theme, the cache plugin, and Square Add-On all at once on a live payment form. A safer sequence is: site copy, updates, test form, Sandbox payment, entry check, then rollout to the live site.

HTTPS and payment page security

The page with the payment form needs working SSL. The Square Add-On documentation explicitly lists SSL as a prerequisite. This is not only about user trust, but also about how the browser and payment SDK handle secure fields. If the site loads over HTTP, if there is mixed content, or if the form page is served through an unstable proxy, fix HTTPS first.

Critical pre-test check: the form page must load over https://, with no browser warnings and no JavaScript errors in the console. Otherwise, do not start troubleshooting the Square feed yet. Fix the page security baseline first.

Gravity Forms and Square currency

One of the most common causes of connection issues is a currency mismatch. Gravity Forms documentation warns that the Gravity Forms currency setting must match the currency of the Square account. If the currencies differ, the error may appear as early as account connection or feed creation. Check Forms -> Settings and the Square account settings before you build the form.

If the site accepts payments in one country, keep the form, prices, email notifications, and Square location aligned within one currency model. Do not rely on hidden conversions through custom fields unless you have separate, validated business logic for that. Gravity Forms should send Square a clear amount in the expected currency.

Sandbox before Live

Square Sandbox exists so you can run tests without charging real money. Square documentation describes Sandbox as an isolated environment with test accounts and test payment values. For Gravity Forms Square, this is the best way to validate the initial setup: you can confirm that OAuth works, the form contains the required fields, the feed sends the amount, and Entry Detail receives the payment status.

Sandbox has limitations. Square explicitly notes that some parts of the production Dashboard may be missing or behave differently. In the Gravity Forms Square context, this matters especially for the receipt URL: the documentation for the {square_receipt_url} merge tag states that receipt links are not supported in Sandbox and may lead to an error page. So do not conclude that the receipt link is broken in Live mode based only on a Sandbox test.

Installing and connecting Square in the admin panel

Standard installation goes through the add-on catalog inside Gravity Forms. In WordPress, open Forms -> Add-Ons, find Square Add-On, install it, and activate it. After activation, go to Forms -> Settings -> Square. That is where you choose the mode and complete the OAuth connection to Square.

Square Add-On has two fundamentally different modes: Sandbox and Live. Sandbox sends data to Square’s test environment and does not create real charges. Live works with the real account and can trigger real payments. On a new site, start with Sandbox even if the form looks simple. With payments, "I’ll just test it quickly on the live site" often ends in accidental charges, unclear refunds, and accounting confusion.

When connecting Live mode, click Connect with Square, sign in to Square, approve the permissions, and return to WordPress. After a successful connection, the settings should show a status such as Connected to Square as and let you choose a Business Location if the account has multiple locations. Save the settings. If the wrong location is selected, payments may go somewhere other than where the business owner expects.

Sandbox connection nuance

Sandbox has one separate nuance: before starting the OAuth connection, you need to open the Sandbox Seller Dashboard from the Developer Dashboard in the same browser and keep that tab open. The official Gravity Forms documentation gives the characteristic error message: To start the OAuth flow for a sandbox account, first launch the seller test account from the Developer Dashboard. If you see that error, the problem is not WordPress and not the add-on license. You need to open the Square test account, then retry the connection from Forms -> Settings -> Square.

After connecting Sandbox, save the settings and do not switch modes until all checks are complete. Switching between Sandbox and Live changes the environment that receives the payments. That means a successfully created Sandbox entry does not prove that the Live account is connected. Before accepting real payments, repeat the OAuth connection in Live mode and run a minimal control scenario based on the site owner’s rules.

What counts as a successful connection

A successful connection is not just the absence of an error after OAuth. Check four signs: the mode is intentionally selected, the account is shown as connected, the Business Location matches the correct Square location, and the settings save without warnings. If any one of those is missing, do not move on to the form. Otherwise, you risk building the right form in the wrong payment environment.

A Square-compatible form: fields, amount, and where Square Field belongs

The next layer is the form itself. Gravity Forms documentation lists the required elements for a Square-compatible form: a Pricing field, a Square field, a Name field, an Email field, and an Address field. In practice, that means the plugin needs not only card data, but also customer details, and the amount must be calculated through Gravity Forms pricing fields.

Do not replace Square Field with the old Credit Card Field. The official Gravity Forms documentation explicitly says the old credit card field is no longer recommended for modern payment add-ons, and gateway-specific fields should be used instead: Square Field, Stripe Field, PayPal Field. If an older form still contains Credit Card Field, migrate it to Square Field and retest the feed.

Pricing fields and amount calculation

Use Pricing Fields for the amount: Product, Option, Quantity, Shipping, Total. The Product field has several modes: single product, drop-down, radio buttons, user-defined price, hidden product, or calculation. The important thing is that the selected mode is clear to the feed. If you plan to send the form total, the page should include a properly configured Total field or a group of fields from which Gravity Forms can build the final amount.

Choice-based Product fields have a separate trap: if the labels contain special characters, Gravity Forms documentation recommends enabling values and assigning simple unique values. This matters for calculations, conditional logic, and state validation. For payments, it is better to keep the technical values simple: basic, standard, premium, while showing the human-readable names separately to the user.

A safe rule for a first payment form: one Product field with clear options, one Total field, one Square Field, required Name, Email, and Address fields, and then a Square feed that pulls the amount from Total. Add complex calculations only after the basic payment flow works in Sandbox.

Where to place Square Field

Square Field lives in the Pricing Fields group and adds card input handled by Square. Place it after the product selection and total amount fields so the user understands what they are paying for before entering payment details. If the form is multi-page, the documentation recommends placing Square Field on the final page. That makes sense: payment should not appear before the user has chosen the service, entered contact details, and seen the total.

If you use conditional logic with multiple payment methods, do not mix fields without a clear structure. For example, you can show Square Field only when the user chooses card payment through Square, and show a different field for another payment processor. But the feed must follow the same logic. The visible field and the triggered feed should describe the same payment path.

What to do with the eCommerce Form template

For a quick start, you can use the ready-made Gravity Forms eCommerce template and remove what you do not need. But do not trust the template blindly. Check which Product fields it already includes, whether there is an old credit card placeholder, how the Total field is named, which fields are required, and whether they create friction in the user flow. The template speeds up assembly, but it does not know your business logic.

For paid registrations, small orders, or donations, a short form is usually enough. The more fields you place before payment, the more likely people are to abandon the page. Move secondary questions to a follow-up email, a separate form, or the team’s internal workflow. Gravity Forms Square should handle the payment moment, not turn into a twenty-question intake form for no reason.

Square feed: where payment type and processing logic are defined

The feed is created inside the specific form: open the form, go to Settings -> Square, click Add New, give it a name, and choose the transaction type. Square Add-On documentation describes two main types: Products and Services for one-time payments and Subscriptions for recurring charges. This is not a cosmetic choice. It determines which settings appear and how the resulting entry should be diagnosed later.

Products and Services

A one-time payment works for a service, a product without a complex cart, a ticket, a deposit, a consultation, or a one-time donation. In the feed settings, choose the Payment Amount. This can be a specific Product field or the form total. If the form includes several pricing elements, Total is usually the better choice so Square receives the fully calculated amount.

For one-time payments, the Authorize Only option is available. It tells Square to validate and authorize the card, but not capture the money immediately. Payment capture is completed later from the Gravity Forms entry. This is useful for orders where you first need to confirm availability, approve terms, review an application, or prepare fulfillment. But authorizations have an expiration period defined by Square, so they should not be treated as an indefinite hold.

Subscriptions

Subscriptions are used for recurring payments: memberships, monthly support, service retainers, passes, installment plans, or recurring deliveries. In the feed, you choose the Recurring Amount and the Billing Cycle. Gravity Forms documentation explains that the cycle is defined by a period such as day, week, month, or year, along with the number of subsequent charges. The Continuous option means billing continues until cancellation.

The biggest mistake with subscriptions is assuming they are just one-time payments repeated several times. A subscription affects the form copy, confirmation, notifications, cancellation policy, CRM record, or membership system. If the user is buying a plan, they need to understand the billing interval, the amount, and the conditions. If the subscription is tied to a user role, think through what happens when the subscription is created and when it is canceled.

Billing Information

In the Billing Information section, you map your form fields to Square fields: email, name, and address. Email and name are listed in the documentation as required for submission. Do not leave this mapping "for later." If the form collects name in a single field but Square expects separate parts, check how Gravity Forms passes the data. If the address is optional for the user but required for your workflow, it is better to make it required in the form than to try reconstructing it after a failed payment.

Conditional Logic for multiple scenarios

Feed conditional logic lets you run Square only for certain answers. For example, a registration form may offer "pay now" and "request an invoice." In the first case, the Square feed runs; in the second, payment does not start and the team receives a notification instead. Another example is two Square feeds in the same form: one-time payment for one selection and a subscription for another. A setup like that should be tested branch by branch.

Test not only the successful branch, but also the branch where the feed should not run. If the condition is wrong, the user may submit a request without paying when payment is required, or see a payment error in a scenario where you promised a manual invoice.

Gravity Forms Square mechanics worth understanding

This product has a few mechanics that make it different from "just a form with payment." If you understand them upfront, setup becomes manageable and troubleshooting gets much faster. What follows is not a generic Gravity Forms overview, but specifically the logic of the Square Add-On: where the setting lives, what the admin enters, what the plugin changes, what appears after submission, and where the limitation is.

Square Field as secure payment input

Where to set it: the form editor, under Pricing Fields. The administrator adds Square Field, and the visitor enters card details into a field powered by Square. The plugin should not turn the site into a card number storage system. The visible result is a payment block in the form with card details and cardholder name.

How to test it: open the form page in Sandbox, enter Square test data, and submit the form. If the field does not appear, check HTTPS, JavaScript errors, cache, and whether a feed exists. If the field appears but submission fails, move to Entry Detail and logs instead of changing the form design blindly. Limitation: the old Credit Card Field should not be used as a substitute for Square Field in modern Square workflows.

Transaction Type as the business-process switch

Where to set it: Settings -> Square inside the form. The administrator chooses Products and Services or Subscriptions. The plugin changes the available feed fields: for a one-time payment, Payment Amount and optional Authorize Only matter; for a subscription, it is Recurring Amount and Billing Cycle. The visible result is different statuses and actions in the form entry.

Failure symptom: you expected a subscription, but the entry looks like a one-time payment, or the reverse. Fix: check the correct feed, disable extra feeds, and make sure conditional logic is not triggering the wrong scenario. Limitation: transaction type cannot be chosen by guessing from the form name. It has to match the financial promise made on the page.

Authorize Only as delayed capture

Where to set it: the Products and Services feed. The administrator enables Authorize Only when the payment should be captured later. After the form is submitted, the plugin creates an authorization, and Entry Detail shows the Authorized status, transaction ID, a notice about the authorization window, and a Capture Payment button. After capture, the status changes to Paid and refund options become available.

The visible result for the team is that the request has already validated the card, but the funds have not been charged yet. That works well for reservations, manual approvals, or fulfillment after an availability check. Limitation: the authorization is temporary. If the team does not capture the payment in time, the money will not be charged and the process will have to be repeated according to Square’s rules.

Subscription Details in the form entry

Where to check it: Entry Detail for the entry that triggered the subscription feed. Gravity Forms documentation says it shows the subscription status, start date, subscription ID, and recurring amount. If the subscription is active, the entry also includes an option to cancel it. That is convenient for an administrator who works in WordPress and does not want to look up the subscription in Square every time.

The limitation here is important: Gravity Forms documentation warns that subscription cancellation is handled from the Gravity Forms entry, and Square does not provide a separate cancellation interface in this context. If the entry is permanently deleted, the related subscription may no longer be manageable from Gravity Forms. Do not delete payment entries while subscriptions, refunds, or accounting review are still open.

Refund Payment from Entry Detail

For one-time Products and Services payments, you can initiate a refund from the Gravity Forms entry if the entry status is Paid. After clicking Refund Payment, the plugin sends the request through Square and updates the screen with pending refund details. For subscriptions, the documentation directs you to the Square Dashboard and Square’s own procedures. That split should be reflected in your support instructions.

How to verify it: after the refund, the entry should show an updated status or refund details, and Square should reflect the same information. If the refund does not go through, do not click the button repeatedly. First check the entry status, transaction type, Square availability, and administrator permissions.

Receipt URL merge tag

The {square_receipt_url} merge tag outputs the Square receipt URL for the transaction tied to the entry. It can be used in notifications or post-payment confirmations, but with two caveats. First, the link is not available until the payment is captured. Second, Sandbox does not support receipts, so a Sandbox link may lead to an error. That does not automatically mean the form is broken.

The best approach is to display the receipt URL in messages that run after a payment has successfully completed, not in a generic "Form is submitted" notification. For delayed capture, send the receipt after capture, not after authorization.

Practical scenario: workshop registration with payment and manual approval

Imagine a small studio website offering a workshop. You need to accept registrations, collect name, email, and phone number, let the user choose a pricing tier, collect card details, but capture the money only after checking whether there is still space available. This is a classic case where Gravity Forms Square is more practical than a full cart: the form collects context, Square validates the payment data, and the administrator decides when to capture the payment.

Goal

Create a form where the participant chooses a pricing tier, enters contact details, and submits card information. After submission, the administrator sees an entry with Authorized status, confirms there is space in the group, and then clicks Capture Payment. If no spots are available, the team does not charge the card and contacts the participant instead.

Preparation

The site should have Gravity Forms and Square Add-On installed, Square Sandbox connected, matching currency in Gravity Forms and Square, and the form page should load over HTTPS. If you are connecting Sandbox, the Square Developer Dashboard test seller account should already be open. On the WordPress side, it is also a good idea to temporarily disable aggressive JavaScript optimization on the form page if the cache plugin combines or defers scripts.

Form setup steps

1. Create a new form in Forms -> New Form and give it a name the team will recognize, such as Master Class Registration.
2. Add Name, Email, and phone if needed. Make Email required because it is used in Billing Information and notifications.
3. Add Address. Even if the business does not need a full address, still verify which fields your Square feed and payment handling rules require.
4. Add a Product field with pricing tier options. If there are several tiers, Radio Buttons with simple values work well.
5. Add Total so the user can see the final amount before entering card details.
6. Add Square Field from Pricing Fields. Place it after Total and before the submit button.
7. Save the form and open Settings -> Square.
8. Create a feed, choose Products and Services, set Payment Amount to Total, enable Authorize Only, map Billing Information, and save the settings.
9. Configure an administrator notification for the Payment Authorized event so the team reacts to a confirmed authorization rather than a bare form submission.
10. In the user confirmation, state that the registration has been received and will be confirmed after availability is checked. Do not describe the payment as complete before capture.

Verification

Open the page with the form, choose a pricing tier, fill in the contact fields, and submit test data in Sandbox. After submission, go to Entries and open the entry. Under Payment Details, you should see Authorized status, a transaction ID, and an action to capture the payment. After manual capture, the status should change to Paid. Also verify that the administrator email was triggered on Payment Authorized or Payment Completed, depending on the logic you chose.

The nuance people often miss

If the administrator immediately sends the user an email saying "payment received" while the feed is set to Authorize Only, that message makes a false promise. This scenario needs two different texts: one after authorization and another after capture. Gravity Forms notification events make it possible to separate those emails by payment event. The notification wording should always match the actual status shown in Entry Detail.

Subscriptions, installment plans, and scenarios with extra add-ons

Subscriptions in Gravity Forms Square are useful when you are selling a recurring commitment rather than a one-time product: monthly membership, project support, a service plan, a subscription pass, or installments. In the feed, choose Subscriptions, then set the Recurring Amount and Billing Cycle. If you use a limited number of cycles, keep the documentation logic in mind: the number of cycles after the initial charge determines the overall payment term.

Transparency matters for the user. The form should clearly state the amount, the billing frequency, and the cancellation terms. Do not hide recurring billing in fine print. If the customer selects "monthly," the confirmation text and the email should both repeat that a subscription was created, not a one-time payment. If the subscription controls site access, define in advance which add-on changes the user role and what happens when the subscription is canceled.

Subscription plus User Registration

The official Square integration page mentions using it together with User Registration: an account or role can be created after a successful payment. In a real project, that works well for a mini-course or a private membership club. The division of responsibility is straightforward: Square Add-On handles the payment, User Registration handles creating the user or changing the role, and Gravity Forms handles the conditions, notifications, and entries.

The setup order should be careful. First test the Square feed on a simple form. Then add the User Registration feed and make sure it runs after payment, not immediately after submission. If the user gets access before the payment is confirmed, the issue may not be Square itself, but rather the order of delayed feeds or the event tied to registration.

Subscription plus Advanced Post Creation

Another scenario is paid content submission. The user submits a form, pays for the listing or publication, and Advanced Post Creation creates the post only after payment succeeds. This is a good fit for an event directory, job board, or classified site where you want to accept content but publish it only after payment and moderation.

Limitation: do not create critical content before payment is confirmed if the business logic requires payment before publication. It is safer to save a draft, notify the moderator, and publish only after the status is Paid. If you are using Authorize Only, the team must understand that Authorized is not the same as Paid.

Installments through a subscription with a limited cycle

An installment plan can be implemented as a subscription with a limited number of charges. For example, the first payment is taken immediately and then several more recurring charges follow. The feed documentation explains that the numeric billing cycle value represents the number of charges after the initial charge. That means the wording on the form needs to be extremely precise: if you promise three total payments, make sure you have not actually configured an initial charge plus three renewals.

Before launching this kind of scenario, create a simple internal table for the team: what the user sees, what is defined in Product, which Recurring Amount is selected, how many cycles are set in the feed, what will appear in Entry Detail, and where the subscription is checked. That is not bureaucracy. It is protection against a financial mistake.

Verifying the result: what to check after form submission

Result verification should happen in several places. You cannot stop at "the form submitted successfully." For a payment form, successful submission only means WordPress accepted the submission. You still need to verify that Square received the payment instruction, Gravity Forms recorded the correct status, notifications fired on the right event, and the user saw the correct confirmation.

Entry Detail and payment statuses

Open Forms -> Entries, select the entry, and review Payment Details. Gravity Forms documentation describes several statuses: Paid, Authorized, Active, Failed, Pending, Processing, Refunded, Voided, and others. Not every payment add-on uses every status, but for Square the most important ones are Paid, Authorized, Active, and Refunded.

For a one-time payment without Authorize Only, expect Paid after successful completion. For delayed capture, expect Authorized until manual capture. For subscriptions, expect subscription information and an active status. If the entry exists but there is no payment section, check the feed and Square Field. If the status is Failed, look at card data, amount, currency, Sandbox values, or the Square response.

Square Dashboard

After a Sandbox test, check the Square Developer Dashboard or Sandbox Dashboard. Keep Sandbox limitations in mind: some production features may be unavailable. For Live mode, review the real Square Dashboard as part of an approved test with the site owner. The goal is to confirm that the amount, location, and status match what you see in Entry Detail.

Notifications

Gravity Forms notification events let you tie emails to payment events. For Square, that includes events such as Payment Authorized, Payment Completed, Payment Refunded, Payment Failed, and Subscription Canceled. Configure those emails so they do not mislead either the user or the team. If the payment is only authorized, do not write "paid." If a subscription is canceled, the email should explain what happens next with access or service.

Receipt URL

If you use {square_receipt_url}, test it only in the appropriate event. The merge tag will not provide a valid link before payment capture. In Sandbox, receipt links are not supported by Square, so do not treat Sandbox as the only evidence that the receipt link is broken.

Notifications, confirmations, and handing the request off to the team

After a successful Sandbox test, many administrators assume the setup is finished. For a simple contact form, that is at least understandable, but for payments it is not enough. A payment form needs not only to collect money, but also to send the right signal to the user, the administrator, accounting, the service manager, and any related add-on. If the wrong event is selected, the team may start work on an unpaid request or miss a successful payment entirely.

Gravity Forms includes the standard Form is submitted event and additional payment events provided by payment add-ons. For Square, the key ones are Payment Authorized, Payment Completed, Payment Refunded, Payment Failed, and Subscription Canceled. They matter because form submission and payment completion are not the same thing. A user may submit the form but the payment process may still return a decline. Or the form may authorize the card through Authorize Only while the money has not yet been captured.

How to split emails by actual status

For a one-time payment without delayed capture, it is usually enough to send the customer an email after Payment Completed and send the team an email on the same event. In the customer email, say that the payment was received, the request was recorded, and the next step depends on the service: wait for confirmation, go to an instruction page, expect a follow-up email with details, or wait for a manager to reach out. Do not include internal transaction IDs unless the customer is actually expected to use them.

For Authorize Only, you need at least two separate messages. The first comes after Payment Authorized: the request was received, the card was validated, and the final charge will happen after confirmation. The second comes after capture, when the status becomes Paid: payment is complete, and the order or booking is confirmed. If you also need a decline or cancellation path, create a separate message for the team so they do not have to investigate the issue manually in Square.

For subscriptions, the email should explain the billing frequency and the next step. If the subscription grants access to a protected area, the email should be sent only on the event that truly means the subscription was created successfully and the related access has started. If the user role is changed by the User Registration Add-On, verify that its feed does not run before payment. Emails should be tied to actual payment events, not to the hope that payment succeeded.

Confirmation on the form page

The confirmation is the message the user sees immediately after submission. It should not be written the same way for every scenario. If the payment completes instantly, the confirmation can say the payment was successful. If Authorize Only is used, it is more accurate to say the request was received and the card was authorized, and that final confirmation will come after review. If the user chose a branch without online payment, the confirmation should explain who will follow up and when regarding the invoice.

For redirect confirmations, make sure the thank-you page is not cached as if it were identical for every status. Do not display sensitive entry data on a public page. If you need to show personal details, use a validated access mechanism rather than passing them in the URL. For most scenarios, a short message plus a follow-up email is enough.

Role distribution inside the team

Payment forms often break down organizationally, not technically. One person manages the site, another manages Square, a third handles service delivery, and a fourth handles refunds. If nobody understands what each status means, Entry Detail turns into a list of unclear labels. Create a short internal map:

This kind of table is more useful than a vague instruction to "check everything." It reduces the chance that accounting cancels a subscription from the wrong place, a manager confirms an unpaid request, or a developer starts changing PHP before checking the currency settings.

Form data, privacy, and entry storage

Gravity Forms Square should not turn WordPress into a storage system for card numbers. Card input is handled by Square Field, while WordPress stores the form data and payment metadata needed to process the request. Even so, that still includes personal and business data: name, email, address, amount, selected service, transaction ID, payment status, notes, and sometimes internal team comments.

Before launch, decide who has access to Forms -> Entries. Do not give site editors permission to view payment entries just because they know how to edit pages. For a payment form, access should be limited to the people who actually process requests and refunds. If the site uses roles and access restrictions through additional plugins, test them on a copy of the site: someone without the proper role should not be able to see payment entries.

What should not be stored in the form

Do not ask users to enter extra financial data into regular Gravity Forms fields. Card number, CVV, bank details for card payments, and similar sensitive information should remain inside the secure Square payment field, not inside a plain text field called "Comment." If the business needs a tax ID, address, or legal details, collect only what is genuinely required to deliver the service and handle reporting afterward.

If the form is tied to donations, medical services, education applications, or personal consultations, review the data retention policy separately. Gravity Forms provides tools for entries, but responsibility for retention periods, permissions, and consent text still belongs to the site owner. Do not promise users more than the system is actually configured to provide.

Why entries should not be deleted automatically

For ordinary lead forms, people sometimes set up automatic cleanup of old entries. For Square workflows, that is risky. The entry is the connection point between the form, payment status, subscription details, refund actions, and internal history. Square subscription documentation especially emphasizes the risk of deleting an entry because subscription cancellation is handled from the Gravity Forms entry.

A good practice is to split retention policy by form type. Lead forms can follow one rule, while payment forms should follow another rule after refunds, subscriptions, and accounting reconciliation are fully closed. If you still delete old entries, first export the reporting data you need and confirm that no active subscriptions depend on those entries.

Checking after form changes

Any change to a payment form can affect the feed. If you renamed a Product field, removed Address, changed choices, added conditional logic, or moved Square Field to another page, you need to run the Sandbox test again. Pay special attention to forms where the Product field is used in Payment Amount or Recurring Amount. If the field was removed or replaced, the feed may still point to the old structure.

The maintenance rule is simple: after every change to fields, conditions, feeds, notifications, embed method, or cache settings, run a short payment test. Do not wait until the first real customer becomes your tester.

Security, presentation, and careful improvements

A payment form needs to be not only functional, but also clear. The user should see the final amount before entering card details, understand whether the payment is one-time or recurring, and get a clear response after submitting the form. But any form enhancement should not break the payment SDK, hide errors, or interfere with how data is sent to Square.

What can be improved safely

It is usually safe to improve the elements around the form: helper text, field order, pricing descriptions, the form container styling through Gravity Forms theme settings, confirmation messages, and notifications. Be cautious with JavaScript optimizers, lazy-loading scripts, file combination, and popups. If Square Field loads inside a tab, modal window, or page builder block, test the same form on a clean page with a standard Gravity Forms block.

For appearance, it is better to start with the Theme Framework and block/shortcode settings rather than writing CSS against Square’s internal markup. Square Field is powered by the payment SDK, and its internal field cannot always be styled as freely as a standard input. If you specifically need control over card field styling, the official Square filters include gform_square_card_details_style, but it should be used only by a developer who understands which values Square Web Payments SDK accepts.

Temporary diagnostics through the debug constant

The Square Add-On changelog documents support for the GF_SQUARE_DEBUG constant for logging Square REST API requests and responses. This is not a setting for permanent use on a live site. Use it only on a test copy or briefly during controlled troubleshooting, then disable it and remove any unnecessary logs.

// Custom adaptation of the officially documented Square Add-On debug constant.
// Location: wp-config.php on a test copy of the site, or temporarily on production during controlled troubleshooting.
// Remove after testing, or change true to false.
define( 'GF_SQUARE_DEBUG', true );

Verification after enabling it: rerun a single test scenario, download or review the Gravity Forms logs, locate the Square response, and then disable the constant. Rollback: remove the line or set it to false. Do not keep debug logs longer than necessary, and do not share them with a contractor before removing sensitive data.

Compatibility with cache and page builders

Official Gravity Forms troubleshooting recommends checking for conflicts with the theme, plugins, page builders, and script optimizers. For Square Field, that is especially relevant because the payment field depends on JavaScript and secure loading. If the form works on a simple test page but breaks inside a complex layout, the cause is often not the Square feed but the container, caching, deferred loading, or a third-party script.

A practical sequence is this: create a clean page in the standard editor, insert the Gravity Forms block, disable JavaScript minification and combination for that page, and test the form in Sandbox. If everything works there, return to the main layout and re-enable elements one by one. That helps you separate a payment problem from a layout problem much faster.

Gravity Forms Square errors and symptom-based troubleshooting

Troubleshooting a payment form should start with the symptom, not with random setting changes. Below are issues that are especially typical for Square Add-On, Gravity Forms payment feeds, and the WordPress environment. Each case includes the likely cause, what to check, how to fix it, and when it makes sense to roll back a change.

Unable to connect Square in Sandbox

Symptom: after clicking Connect with Square, you get an error saying that the seller test account must be opened first from the Developer Dashboard. Gravity Forms documentation confirms the reason: Sandbox OAuth requires the Sandbox Seller Dashboard to be opened beforehand in the same browser.

What to check: sign in to the Square Developer Dashboard, open the Sandbox test account, make sure that tab is active, then retry the connection from WordPress. Fix: do not change the form or feed until the account connection is complete. If the error disappears, save the Square Add-On settings. Rollback is only needed if you accidentally connected Live instead of Sandbox. In that case, switch back to Sandbox mode and repeat authorization.

Currency error during connection or feed creation

Symptom: Square will not connect or the feed cannot be created because of a currency error. Cause: the Gravity Forms Currency Settings do not match the currency of the Square account or the selected Business Location. This is stated directly in the Square Add-On documentation.

What to check: Forms -> Settings, the site currency, the Square account settings, and the selected location. Fix: align the currencies before creating the feed. If the form already exists, recheck Product and Total after changing the currency. Rollback: if changing the currency would break other payment forms on the site, do not change the global currency blindly. Plan a separate migration or use a separate site/account for the required region.

Square Field does not appear on the page

Symptom: the form loads, but the card field is missing or shows an error. Possible causes include a non-HTTPS page, a JavaScript error, a theme or plugin conflict, aggressive script optimization, a form inside a complex page builder container, or Square Field being removed or hidden by conditional logic.

What to check: HTTPS, the browser console, whether Square Field is present in the editor, a clean test page with the Gravity Forms block, and cache disabled for the form page. Fix: first get the form working on a simple page, then restore the layout. Rollback: if a script optimizer breaks the field, keep an exclusion for the form page or disable that specific optimization instead of rebuilding the form.

The form saves an entry, but no payment reaches Square

Symptom: an entry appears, emails may be sent, but Square shows no payment. The most likely reason is that the Square feed is missing or disabled, Payment Amount is not configured, the feed conditional logic did not match the user’s response, or the form does not contain the required Square Field.

What to check: Settings -> Square in the specific form, whether the feed is active, Transaction Type, Payment Amount or Recurring Amount, Billing Information, and feed conditions. Fix: create a minimal feed without complex conditional logic, test in Sandbox, and then reintroduce conditions. Rollback: if a new feed accidentally runs for every form variation, disable it until the conditions are verified.

The subscription was created differently than expected

Symptom: you expected recurring billing, but got a one-time charge, or the number of charges does not match what the page promised. Cause: the wrong Transaction Type was selected, Billing Cycle was misunderstood, or the recurring amount is being pulled from the wrong field.

What to check: a Subscriptions feed, the Recurring Amount, billing period, number of billing cycles, and the wording in the form and confirmation. Fix: test the subscription in Sandbox with a small test amount and inspect Entry Detail. Rollback: do not delete a subscription entry before canceling the subscription. If the subscription is active, cancel it from Entry Detail as described in Gravity Forms documentation.

Receipt URL does not work in Sandbox

Symptom: the {square_receipt_url} merge tag returns nothing or the link leads to an error in the test environment. Possible cause: the receipt does not exist yet, the payment was not captured, or you are testing in Sandbox where Square does not support receipts.

What to check: the entry status, the notification event, when the merge tag is processed, and the Square mode. Fix: use the receipt URL after Payment Completed or after capture, and treat Sandbox as a limited verification method. Rollback: if you inserted the receipt URL into a standard Form is submitted notification, move it to a payment-specific notification.

The form admin screen freezes or the field cannot be added

Symptom: the form editor becomes unresponsive, Square Field cannot be added, or the interface breaks. In Gravity Forms support discussions, cases like this were linked to probable theme or plugin conflicts when support could not reproduce the issue on a current set of Gravity Forms, Square Add-On, and WordPress versions.

What to check: reproduce the conflict on a site copy using the official Gravity Forms method: temporarily switch to a default theme, keep Gravity Forms and the required official add-ons active, then re-enable third-party plugins one by one. Fix: update the conflicting component or contact its support team. Rollback: restore the original theme and plugins only after you have identified the cause, or the problem will likely return.

How to decide the form is ready for launch

Before turning on Live mode, put together a short launch checklist. It should not be formal for the sake of formality. It should be verifiable. Review it with someone who understands the business scenario and with the person responsible for the site. A payment form affects the user, finances, and data, so "it opened for me" is not enough.

• The form opens over HTTPS and shows no browser warnings.
• The Gravity Forms currency matches the Square account currency and the selected Business Location.
• The form includes a Product or other Pricing field, Total, Square Field, Name, Email, and Address.
• Square Field appears after amount selection and is not hidden by accidental conditional logic.
• The feed is active, clearly named, and set to the correct Transaction Type.
• Payment Amount or Recurring Amount is pulled from the correct field.
• Billing Information is mapped to real form fields.
• Notifications are tied to payment events, not just form submission.
• The Sandbox test created an entry with the expected status.
• The team knows what to do with Authorized, Paid, Active, Failed, and Refunded.

After switching to Live, do not change the form text, conditions, feed, and placement page all at once. First switch the Square mode, connect the live account, choose the correct Business Location, and save the settings. Then test the form with a minimal scenario approved by the site owner. If Authorize Only is used, test not only the authorization, but also the manual capture.

If payments matter to the business every day, create a separate internal verification page or support checklist. It should include the form URL, feed name, Square mode, expected status, who receives the email, where to check Entry Detail, and when to escalate to the developer. That dramatically shortens response time when a user writes, "my card won’t go through."

When Gravity Forms Square is the right choice

Gravity Forms Square is worth using when you need a WordPress payment form where the amount, conditions, and next steps depend on the user’s answers. It is not just a "pay now" button, but a managed chain: the form fields collect data, Pricing Fields build the amount, Square Field collects payment details, the feed sends the transaction to Square, and Entry Detail remains the administrator’s working control point.

Before launch, make sure you have covered the main path: HTTPS, matching currency, connected Square account, a compatible form, a correct feed, Sandbox testing, payment notifications, and clear instructions for the team. If those pieces are in place, you can download the ZIP archive and test the product on your own site in a controlled environment.

If you need a full store with a cart, stock management, and catalog synchronization, choose an eCommerce solution instead. If you need a different payment method mix, compare Stripe and PayPal. But for requests, registrations, services, donations, memberships, and smaller payment scenarios inside Gravity Forms, this add-on remains a practical solution because it connects payment with form data and gives the administrator a clear point of control.