=== Payments Square Connect ===
Contributors: wppayments
Tags: woocommerce, square, payments, contact form 7, subscriptions
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.5
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Square Hosted Checkout for WooCommerce and Contact Form 7. Connect once for one-time and subscription payments.

== Description ==

**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](https://developer.squareup.com/apps) 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.

== Installation ==

= Minimum setup (all sites) =

1. Activate **Payments Square Connect**.
2. In the admin sidebar, open **Payments Square Connect**.
3. Select **Sandbox** or **Live**.
4. Click **Payments Square Connect**, complete Square sign-in, and select a **Square Location**.
5. Click **Save connection settings**.

= WooCommerce store =

1. Finish minimum setup above.
2. Go to **WooCommerce → Settings → Payments → Payments Square Connect**.
3. Enable the gateway and set the checkout **Title** and **Description**.
4. Save and test a checkout in Sandbox first.

= Contact Form 7 =

1. Finish minimum setup above.
2. Edit a form and add `[square_pay amount:25.00]` or `[square_subscribe variation:ID name:"Plan" amount:15.00]`.
3. Publish and submit the form to test the redirect to Square.

= Subscriptions =

1. Create subscription plans in Square Catalog.
2. Open **Payments Square Connect → Subscription Plans** → **Refresh from Square**.
3. Use variation IDs in CF7 tags or map them on WooCommerce subscription products.

= Checkout appearance (Live only) =

1. Switch to **Live** on the Connect screen.
2. Open **Payments Square Connect → Checkout Settings**.
3. Adjust merchant and location options, then save.

== Frequently Asked Questions ==

= Do I need WooCommerce? =

No. You can use Contact Form 7 payments without WooCommerce. WooCommerce is only required if you want to sell through a WooCommerce store checkout.

= Do I need Contact Form 7? =

No. If you only sell through WooCommerce, you do not need CF7. Install CF7 only when you want form-based payments.

= Where is the main settings page? =

**Payments Square Connect** in the WordPress admin sidebar. Connection, checkout customization, and subscription plan IDs are all under that menu.

= What is the difference between Sandbox and Live? =

**Sandbox** uses Square's test environment — no real money moves. **Live** charges real cards. Start in Sandbox, then switch to Live when you are ready for production. Checkout Settings only work in Live.

= How does the customer return to my site after paying? =

Square redirects the buyer back automatically. WooCommerce customers land on the **Order received** page. Contact Form 7 visitors return to the same form page with a success message.

= Can I accept recurring subscriptions? =

Yes. Create plans in Square Catalog, then either:

* Add `[square_subscribe]` to a Contact Form 7 form, or
* Map a Square plan variation on a WooCommerce Subscriptions product.

See **Payments Square Connect → Subscription Plans** for variation IDs and setup notes.

= Why is Checkout Settings greyed out or showing a Sandbox notice? =

Square's Checkout Settings API is not available in Sandbox. Connect in **Live** mode to edit payment methods, tipping, branding, and policies.


= How do I contact support? =

Open **Payments Square Connect → Support**. You can send a technical issue by email, start a WhatsApp chat, or post on the [WordPress.org support forum](https://wordpress.org/support/plugin/payments-connect-square/) for the plugin.
= Where do I get the webhook URL? =

On **Payments Square Connect → Payments Square Connect**. Copy the **Webhook URL** and add it in your Square Developer Dashboard if you use webhooks.

= Is card data stored on my WordPress site? =

No. Payment details are entered on **Square Hosted Checkout**. Your site never stores card numbers.

== Screenshots ==

1. Payments Square Connect: connect your Square account, choose Sandbox or Live, pick a location, and copy the webhook URL.
2. Checkout Settings (Beta): manage Apple Pay, Google Pay, Cash App Pay, and other hosted checkout options (Live mode only).
3. Subscription Plans: view Square catalog variations and copy IDs for CF7 square_subscribe tag or WooCommerce Subscriptions.
4. WooCommerce: enable the gateway and set checkout title and description under WooCommerce settings.
5. Contact Form 7: edit a form and add Square payment tags for one-time or subscription checkout.
6. Square hosted checkout (mobile): buyer payment page on Square after redirect from your store or form.

== Changelog ==

= 1.1.5 =
* Checkout Settings: fix Cash App Pay not saving by using Square API field name `cash_app` instead of `cash_app_pay`.

= 1.1.4 =
* OAuth: request `MERCHANT_PROFILE_WRITE` and `PAYMENT_METHODS_READ` scopes during Square Connect so Checkout Settings (Beta) save calls have required permissions.

= 1.1.3 =
* Fix fatal error after Square OAuth return when saving the connection (undefined settings variable).

= 1.1.2 =
* OAuth: store Worker connection key in a dedicated option so Square Connect works on sites without WooCommerce.
* Connect errors: show technical details on the settings screen when **Debug Log** is enabled.
* Clearer messages when OAuth Worker registration or connection key save fails.

= 1.1.1 =
* **Support** admin page: technical issue form (email), WhatsApp link, and link to the WordPress.org support forum.
* Freemius: hide duplicate **Support Forum** submenu entry so support is only under **Payments Square Connect**.
= 1.1.0 =
* Top-level admin menu **Payments Square Connect** with separate screens: connection settings, Checkout Settings (Beta), and Subscription Plans.
* **Checkout Settings (Beta):** retrieve/update Square Checkout merchant settings (Apple Pay, Google Pay, Cash App Pay) and location settings (tipping, branding, policies, customer notes) via the Checkout API.
* **Subscription Plan Checkout:** create hosted checkout links for Square subscription plan variations.
* Contact Form 7 `[square_subscribe]` form tag for subscription signup flows.
* WooCommerce Subscriptions support: map subscription products to Square plan variations; gateway uses subscription checkout when configured.
* **Subscription Plans** admin page lists catalog variations and integration docs.
* CF7 payment return: visible success banner on the form page after Square redirect.
* WooCommerce and Contact Form 7 are optional; plugin core loads without requiring WooCommerce.
* Freemius: auto-resolve clone/safe-mode for Cloudflare tunnel and local dev hosts when the public URL changes.

= 1.0.9 =
* Permanent OAuth return fix: HMAC-signed return state (no transients) and session-based fallback when Worker drops query parameters after Square redirect.

= 1.0.8 =
* Fix OAuth state validation failed after Square redirect by using a transient return state instead of WP nonces (works across external redirects and tunnel URL changes).

= 1.0.7 =
* Fix Connect failures (invalid_return_url): force HTTPS return URLs and re-register the site with the OAuth Worker when the public site URL changes.

= 1.0.6 =
* Ship default OAuth relay URL so Payments Square Connect works on fresh installs without manual Worker configuration.
* Simplified connection settings (merchant Connect UI only).

= 1.0.5 =
* Shared Square connection hub (one Connect for WooCommerce and Contact Form 7).
* WooCommerce gateway settings limited to checkout display options; connection moved to the shared settings page.
* Contact Form 7 support via `[square_pay]` form tag (fixed or field-based amounts).
* Generic Square payment link API used by both WooCommerce orders and CF7 submissions.

= 1.0.4 =
* Freemius SDK integrated for licensing, updates, and analytics.
* Prevent duplicate plugin bootstrap when multiple copies are present.
* Show a short test-mode notice at checkout when environment is Sandbox.

= 1.0.3 =
* Plugin display name adjusted for WordPress.org naming checks (removed restricted wording).
* Main bootstrap file and folder slug aligned with `payments-connect-square` for Plugin Check text-domain validation.

= 1.0.2 =
* Plugin display name updated for trademark guidelines.
* Text domain aligned with plugin slug `payments-connect-square`.

= 1.0.0 =
* Initial release.

