How can we help you?

1. Overview & System Requirements

The Gravity Forms Square Integration Add-on connects your WordPress forms directly to Square’s comprehensive payment ecosystem. Whether you run a brick-and-mortar retail business, a mobile service operation, a professional consultancy, or an eCommerce store, this integration allows you to process secure credit card transactions, digital wallet payments (Apple Pay and Google Pay), and automated recurring subscriptions without redirecting customers away from your site.

By bridging online form submissions with your centralized Square Point of Sale (POS) and Square Dashboard, transaction records, customer contact profiles, inventory counts, and sales metrics synchronize in real time. This unified approach eliminates double data entry and simplifies accounting reconciliation across online and in-person sales channels.

2. Square Developer Setup & API Authentication

To establish a secure API handshake between your WordPress installation and your Square account, you will generate dedicated application credentials in the Square Developer Console.

1. Log in to the Square Developer Dashboard using your standard Square merchant credentials.
2. Click + New Application, enter an application title (such as Gravity Forms Website Checkout), and click Create Application.
3. In the left-hand navigation menu, select Credentials.
4. Locate your Application ID and Access Token. By default, Square displays Sandbox credentials for testing. Toggle the top switch to Production when you are ready to process live transactions.
5. In your WordPress admin dashboard, navigate to Forms → Settings → Square Payment.
6. Select your operating environment (Sandbox for staging/testing or Production for live commerce).
7. Paste your Access Token into the designated password field.
8. Enter your target Location ID (found in your Square Developer Dashboard under Locations). If your business has multiple storefronts or branch locations, specify the location where online transactions should be credited.
9. Click Save Settings. The add-on will ping Square’s v2 endpoints to verify token validity and confirm active connection status.

3. Feed Configuration, Field Mapping & Digital Wallets

A payment feed determines exactly when and how a form submission initiates a transaction in Square. You can configure multiple feeds per form to handle different product lines, ticket tiers, or conditional billing logic.

Step-by-Step Feed Setup

1. Open your target form in the Gravity Forms editor and click Settings → Square Payment in the top toolbar.
2. Click Add New to generate a fresh payment feed.
3. Enter a descriptive Feed Name (e.g. Standard Product Order Checkout or Donation Campaign Feed).
4. Currency Specification: Define the ISO currency code (such as USD, CAD, GBP, AUD, or EUR) corresponding to your Square account domestic currency.
5. Transaction Amount Mapping: Select Form Total or map a specific pricing field (such as a Radio Button product choice or Calculated Number field).
6. Customer Billing Details: Map form fields to Buyer Name, Buyer Email Address, Phone Number, and full Billing Address. Providing accurate customer billing data significantly improves fraud screening passing rates in Square Risk Manager.
7. Digital Wallets (Apple Pay & Google Pay): The add-on integrates Square’s checkout options with automatic eligibility detection. Mobile users on iOS Safari see Apple Pay, while Chrome and Android users see Google Pay automatically.

4. Advanced Payment Workflows & Conditional Routing

Gravity Forms provides unmatched workflow flexibility. When combined with the Square add-on, you can execute sophisticated enterprise transaction flows:

• Multi-Gateway Conditional Branching: Provide radio button options for payment methods (e.g., Pay with Square Credit Card vs Pay with PayPal). Under feed settings, enable Conditional Logic and configure the rule: Process this feed if Payment Method is Square. The form only routes to Square when selected.
• Multi-Location Inventory & POS Routing: For multi-branch businesses (e.g., retail chains, dental offices, regional franchises), create multiple Square feeds filtered by a user dropdown field (e.g. Select Clinic Location). Route transactions to specific Square Location IDs to isolate accounting.
• Automated Post-Payment Notifications: Standard form confirmation emails can be held until Square confirms successful authorization. Prevent order fulfillment emails from dispatching on abandoned or failed checkout attempts.
• Webhook State Engine: Background webhook listeners monitor Square order state transitions. When a customer completes checkout or a merchant issues a refund in the Square POS terminal, the Gravity Forms entry status automatically updates to Paid or Refunded.

5. Troubleshooting & Error Code Matrix

If an API or checkout issue occurs, reference this operational diagnostic matrix to isolate the root cause and apply immediate fixes:

6. Developer Extensibility & Filter Hooks

Developers can hook into the payment lifecycle to append custom order metadata, modify line item charges, or trigger third-party ERP webhooks upon payment settlement.

Modifying Square Payment Payload

Use the filter below to inject custom order notes, internal inventory SKUs, or customer reference numbers into the Square checkout payload before dispatching to the API:

/**
 * Customize Square checkout payload before redirecting to payment link
 *
 * @param array $payload Square checkout order structure
 * @param array $feed Current payment feed settings
 * @param array $entry Submitted Gravity Forms entry
 * @param array $form Current form object
 * @return array
 */
add_filter( 'gform_square_payment_payload', function( $payload, $feed, $entry, $form ) {
    // Append entry tracking ID and custom reference notes
    $payload['order']['reference_id'] = 'GF-ORDER-' . $entry['id'];
    $payload['order']['line_items'][0]['note'] = 'Form: ' . $form['title'] . ' | Submitted on ' . $entry['date_created'];
    
    // Pass custom metadata for accounting reconciliation
    $payload['order']['metadata'] = [
        'wordpress_user_id' => get_current_user_id(),
        'gravity_form_id'   => $form['id'],
        'entry_ip'          => $entry['ip'],
    ];

    return $payload;
}, 10, 4 );

Triggering Custom Fulfillment on Payment Completion

Execute custom business logic (such as provisioning software access or alerting warehouse dispatch) once Square confirms payment:

/**
 * Execute automated post-payment actions upon verified Square settlement
 *
 * @param array $entry Updated entry record
 * @param array $action Completed transaction metadata
 */
add_action( 'gform_square_fulfillment', function( $entry, $action ) {
    $transaction_id = $action['transaction_id'];
    $amount         = $action['amount'];
    $customer_email = rgar( $entry, '2' ); // Replace '2' with your email field ID

    // Example: Log or dispatch internal CRM update
    error_log( sprintf( 'Square Order #%s verified for %s ($%s)', $transaction_id, $customer_email, $amount ) );
}, 10, 2 );

7. Frequently Asked Questions (FAQ)

Q: Does this add-on charge any additional transaction fees?

No. GravityExtra does not charge percentage commissions or per-transaction fees. You only pay standard Square processing rates associated with your merchant account.

Q: Can I test payments in Sandbox before going live?

Yes. The add-on provides a native Sandbox toggle. In Sandbox mode, you can use Square’s official test credit cards to simulate approvals, declined cards, and 3D Secure verification flows without real money transfers.

Q: Does the add-on support Apple Pay and Google Pay?

Yes. Digital wallet capabilities are integrated directly via Square’s modern checkout infrastructure. Customers with enabled Apple Wallets or Google Pay profiles on supported browsers can checkout in a single touch.

Q: How are refunds handled?

When you issue a refund inside your Square Dashboard or physical POS terminal, Square sends a background webhook to your WordPress site. The add-on catches the event and updates the Gravity Forms entry payment status to Refunded automatically.