Payments Square Connect

Descrizione

Payments Square Connect lets you accept card and wallet payments through Square Hosted Checkout. Customers pay on Square’s pages (not on your site), then return to your store or form automatically.

Connect your Square account once. After that, WooCommerce checkout, Contact Form 7 forms, and subscription sign-ups all use the same connection — no duplicate setup.

Getting started in 2 minutes

This short walkthrough covers install → connect Square → first payment:

1. Activate Payments Square Connect.
2. Open Payments Square Connect in the admin sidebar.
3. Choose Sandbox, click Payments Square Connect, sign in, and save a Square Location.
4. Contact Form 7: add [square_pay amount:25.00] to a form and submit a test payment.
5. WooCommerce (optional): enable the gateway under WooCommerce → Settings → Payments.

See the Screenshots section below for each admin screen. A video tutorial will be embedded here once published on YouTube.

Quick start

1. Install and activate the plugin.
2. Open Payments Square Connect in the WordPress admin sidebar.
3. Choose Sandbox (testing) or Live (real payments).
4. Click Payments Square Connect, sign in with Square, and pick a Square Location.
5. Click Save connection settings.
6. Turn on the payment method you need (WooCommerce gateway and/or Contact Form 7 tags — see below).

Where to find settings

Everything is under the top-level menu Payments Square Connect in the WordPress sidebar:

• Payments Square Connect — connect your account, choose Sandbox/Live, pick a location, copy the webhook URL, and enable debug logging.
• Checkout Settings (Beta) — customize how Square hosted checkout looks and behaves (payment methods, tipping, branding, policies). Live mode only — Square does not support this API in Sandbox.
• Subscription Plans — view subscription plan variations from your Square Catalog and copy IDs for forms or WooCommerce products.
• Support – report a technical issue (email form), open WhatsApp chat, or visit the WordPress.org support forum.

Connect Square (required for all payments)

This is the main setup screen. Every payment flow depends on it.

Step-by-step

1. Go to Payments Square Connect → Payments Square Connect.
2. Environment — select Sandbox while testing, or Live when you are ready to charge real cards.
3. Click the Payments Square Connect button and sign in with your Square seller account.
4. After a successful login, choose your Square Location from the dropdown. This location receives payments for WooCommerce orders and Contact Form 7 submissions.
5. Webhook URL — copy the URL shown on this page and paste it into your Square Developer Dashboard webhook settings if you use webhooks for order updates.
6. Debug Log — turn on only while troubleshooting; leave off in production.
7. Click Save connection settings.

Tips

• Use Sandbox first to run test checkouts without moving money.
• If you change your site URL, open this page and connect again so OAuth stays valid.
• Disconnect Square appears after you are connected if you need to switch accounts.

WooCommerce store checkout

WooCommerce is optional. Install it only if you sell products through a WooCommerce store.

Setup

1. Complete Connect Square above (Sandbox or Live + location saved).
2. Go to WooCommerce → Settings → Payments → Payments Square Connect.
3. Check Enable/Disable to turn the gateway on.
4. Set Title and Description — these are what shoppers see on the checkout payment methods list. Example title: “Pay with Square”.
5. Save changes.

How checkout works

• The customer chooses Payments Square Connect at checkout and places the order.
• They are redirected to Square Hosted Checkout to enter payment details.
• After payment, Square sends them back to your Order received page.
• In Sandbox, a test-mode note is added to the gateway description automatically.

WooCommerce Subscriptions (optional)

If you use WooCommerce Subscriptions:

1. Create subscription plans in your Square Catalog (Square Dashboard or API).
2. Open Payments Square Connect → Subscription Plans and click Refresh from Square.
3. Edit your WooCommerce subscription product → General tab.
4. Choose a Square subscription plan variation from the dropdown (leave empty for one-time payment).
5. At checkout, the buyer is sent to Square’s Subscription Plan Checkout instead of a one-time payment link.

Contact Form 7 payments

Contact Form 7 is optional. Install it only if you want to collect payments through forms (donations, fees, registrations, etc.).

One-time payment

1. Complete Connect Square above.
2. Edit your CF7 form and add one of these tags:
   • Fixed amount: [square_pay amount:25.00]
   • Amount from a field: [square_pay amount-field:your-amount] (add a number field named your-amount in the same form)
3. Publish the form. When a visitor submits, they are redirected to Square to pay, then returned to the form page with a success message.

Subscription signup
1. Create plan variations in Square Catalog.
2. Copy a variation ID from Payments Square Connect → Subscription Plans.
3. Add a tag like this to your form: [square_subscribe variation:YOUR_VARIATION_ID name:"Silver Membership" amount:15.00]
* variation (required) — Square subscription plan variation ID, not the parent plan ID.
* name (optional) — label on the Square checkout page.
* amount (optional) — should match the price in Square for that variation.
4. After signup, the visitor returns to the form with a thank-you message.

Subscription Plans

Open Payments Square Connect → Subscription Plans to:

• See all subscription plan variations synced from your Square Catalog.
• Click Refresh from Square after you add or change plans in Square.
• Copy Variation ID values for CF7 [square_subscribe] tags or WooCommerce product mapping.

Square limits to know

• Only variations with one paid phase (or one free trial + one paid phase) work with hosted checkout.
• Cash App Pay and Afterpay are not available for subscription checkout.

Checkout Settings (Beta)

Open Payments Square Connect → Checkout Settings to control Square hosted checkout for payment links created by this plugin.

Important: This screen works in Live mode only. Switch to Live on the Connect screen first; Sandbox shows a notice and fields stay read-only.

Merchant settings tab

• Apple Pay, Google Pay, Cash App Pay — enable or disable wallets on hosted checkout.
• Afterpay / Clearpay — read-only; enable or disable in the Square Dashboard.

Location settings tab

• Customer notes — let buyers leave a note during checkout.
• Tipping — tip percentages, default tip, smart tipping.
• Branding — button color and shape on the Square checkout page.
• Policy — title and description for a policy block on checkout.

Changes are stored in Square and apply to checkout pages this plugin creates.

Requirements

• WordPress 6.0 or later
• PHP 7.4 or later
• Square seller account (Sandbox for testing, Live for production)
• WooCommerce — optional; required only for store checkout
• Contact Form 7 — optional; required only for form-based payments
• WooCommerce Subscriptions — optional; required only to map subscription products to Square plans

External services

This plugin is a client for third-party services. By using it you direct WordPress to contact those services.

• Square (required for payments and connection)

  • What: OAuth, REST API (locations, payment links, catalog search, checkout merchant/location settings), hosted checkout pages, and webhooks.
  • When: When an admin uses Payments Square Connect, when checkout or a CF7 form creates a payment or subscription link, when checkout settings are saved, when subscription plans are refreshed from catalog, and when Square sends webhooks.
  • Endpoints (summary): https://connect.squareup.com or https://connect.squareupsandbox.com (OAuth and API), plus Square hosted checkout URLs returned in API responses.
  • Data sent: OAuth tokens after connection, order/form totals and references, subscription plan variation IDs, checkout setting payloads, and webhook payloads as defined by Square.
  • Terms: https://squareup.com/legal — review Square’s developer and seller terms for your region.

• WPPayments OAuth relay (required for Payments Square Connect)

  • What: Registers your site and completes Square OAuth so application secrets are not stored in WordPress.
  • When: When a store admin clicks Payments Square Connect.
  • Endpoint: https://shc4wc-square-oauth.wordpress-ingenious.workers.dev (override with SHC4WC_OAUTH_WORKER_BASE in wp-config.php if needed).
  • Data sent: Your site URL, sandbox/live environment, and signed session identifiers needed to finish OAuth.
  • Terms: https://squareup.com/legal (Square OAuth); contact the plugin author for questions about the relay service.

Store admins explicitly start OAuth by clicking Payments Square Connect; customers are sent to Square’s hosted pages only during checkout or after submitting a Contact Form 7 payment form.

Privacy

• Site owners: OAuth and API usage are initiated by an administrator with manage_options. Tokens are stored in the WordPress database (options) like other payment settings.
• Customers: Personal and payment data on hosted checkout is processed by Square under Square’s policies, not by card fields on your WordPress site.
• Logging: Optional debug logs may record technical details when debug logging is enabled on Payments Square Connect; disable debug in normal production.
• For compliance questions, consult Square’s documentation and your legal advisor; this readme is not legal advice.