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

WooCommerce Square hosted checkout: onboarding wizard, Pay for Order links, Elementor & Beaver Builder widgets, refunds, wallets.

== Description ==

= Pay on Square's page. Stay connected. Keep stock in sync. =

**Payments Square Connect** is a **WooCommerce Square** integration for merchants who want reliable Square payments — without checkout breaking, surprise disconnects, or inventory falling out of step.

Customers pay on **Square Hosted Checkout** (Square's secure page). You get **WooCommerce Square** orders with **refunds from wp-admin**, **Pay for Order / invoice links**, Contact Form 7, WPForms, Fluent Forms, payment link buttons (shortcode, Gutenberg, Elementor, Beaver Builder), and subscriptions — all through **one Square connection**.

**Why merchants choose this plugin:**

* **No extra plugin fee** on top of Square's processing rates
* **24/7 support** — email, WhatsApp, and the WordPress.org forum
* **Hosted checkout** — no card form in your theme; fewer theme and JavaScript conflicts
* **Automatic token renewal** — Square OAuth stays connected in the background
* **WooCommerce refunds** — full or partial refunds from the order screen
* **SKU inventory sync** — matching SKUs update Square stock when orders are paid
* **Digital wallets** — Apple Pay, Google Pay, Cash App Pay, Afterpay (when enabled in Square)
* **Card data never touches WordPress**

= How this plugin compares =

Many Square plugins embed **card fields in WooCommerce checkout** and/or run **heavy bidirectional catalog sync**. **Payments Square Connect** uses **Square Hosted Checkout** — buyers pay on Square's page, then return to your site.

**Typical on-site / sync-heavy plugins:** card fields that break on checkout, nonce and **EMPTY_VALUE** errors on pay-for-order pages, long sync jobs, duplicate products, stock overwrites, expired tokens, orders marked paid before Square confirms, and refund errors from wp-admin.

**This plugin:** hosted checkout only, **Pay for Order** links without on-site card fields, simple SKU-based inventory (no full catalog import), orders stay **Pending** until Square confirms payment, automatic OAuth renewal, and WooCommerce refunds when a Square payment ID is stored. No paid tier for core checkout.

**Choose on-site sync** if you need full catalog mirroring or gift cards in checkout. **Choose hosted checkout** if you want the simplest, most reliable path — especially when card forms or sync jobs cause problems.

= Get started =

After activation, open **Payments Square Connect → Get started** for the onboarding wizard: Sandbox or Live, connect Square, pick a location, enable WooCommerce gateway in one click, and test checkout. Or use **Payments Square Connect** for full connection settings.

= WooCommerce Square =

1. Connect Square and save a **location**.
2. **WooCommerce → Settings → Payments → Payments Square Connect** — turn the gateway on.
3. At checkout, customers pay on Square Hosted Checkout and return to your **Order received** page.

**Pay for Order:** On unpaid orders, use **Email payment link to customer** or **Copy payment link** on the order screen. Customers pay on Square — no card form on the order-pay page.

**Refunds:** Open a paid order, click **Refund**, enter an amount. Requires a stored Square payment ID (from buyer return or webhook). See FAQ for troubleshooting.

**Subscriptions (optional):** Create plans in Square, copy IDs from **Subscription Plans**, assign to WooCommerce subscription products.

= Payment link buttons =

Add a **Pay Now** button without WooCommerce or a form plugin:

* **Shortcode:** `[square_payment_link amount="25.00" label="Pay Now"]` (alias: `[square_pay_link]`)
* **Gutenberg:** search **Square Payment Link** in the block inserter
* **Elementor:** **Square Payment Link** widget
* **Beaver Builder:** **Square Payment Link** module under **Payments Square Connect**

= Form plugins (optional) =

All use the same Square connection and **Square Hosted Checkout** with your enabled wallets.

**Contact Form 7:** `[square_pay amount:25.00]` or `[square_pay amount-field:your-field]`. Subscriptions: `[square_subscribe variation:PLAN_ID name:"Plan" amount:15.00]`

**WPForms:** Add **Square Hosted Checkout** field; enable **Payments Square Connect** under form Payments.

**Fluent Forms Pro:** Enable **Payments Square Connect** under **Global Settings → Payment → Payment Methods**; add a **Payment Method** field to your form.

Form and payment-link payments are refunded in the **Square Dashboard**, not WooCommerce.

= Admin screens =

Under **Payments Square Connect** in the sidebar:

* **Get started** — onboarding wizard
* **Payments Square Connect** — OAuth, Sandbox/Live, location, webhook URL
* **Checkout Settings (Beta)** — wallets, tipping, branding (Live mode)
* **Subscription Plans** — view and copy Square plan IDs
* **Support** — email, WhatsApp, forum

= Stock sync & connection =

When **SKUs match** between WooCommerce and Square catalog, paid orders can update Square inventory. No matching SKU? Checkout still works by product name and price.

Access tokens **renew automatically** (daily checks and before API calls). The Connect screen shows last renewal time.

= Requirements =

* WordPress 6.0+, PHP 7.4+, Square seller account
* WooCommerce, Contact Form 7, WPForms, Fluent Forms Pro, or WooCommerce Subscriptions — each optional

== Installation ==

1. Activate **Payments Square Connect**.
2. Open **Payments Square Connect** in the admin sidebar.
3. Choose **Sandbox** or **Live**, sign in with Square, and save a location.
4. Enable **WooCommerce Square** checkout, WPForms, Contact Form 7, Fluent Forms, and/or add payment link buttons if you need them.

== Frequently Asked Questions ==

= Does the plugin work with automation or AI tools? =

Yes. Admins with the right capabilities can use the REST API namespace `shc4wc/v1` (for example `GET /wp-json/shc4wc/v1/status` and `POST /wp-json/shc4wc/v1/orders/{id}/send-payment-link`). Developers can hook into `shc4wc_square_connected`, `shc4wc_pay_for_order_email_sent`, and related `shc4wc_*` actions. The optional **AI setup assistant** on **Get started** uses your own OpenAI API key (saved under connection settings) — card data and Square tokens are never sent.

= Do I need WooCommerce? =

No. You can take payments through Contact Form 7 or WPForms without WooCommerce.

= Do I need Contact Form 7? =

No. If you only sell through WooCommerce or use WPForms, you do not need Contact Form 7.

= Do I need WPForms? =

No. WooCommerce and Contact Form 7 work independently. Use WPForms only if you want the WPForms builder.

= Where are the settings? =

**Payments Square Connect** in the WordPress admin sidebar.

= What is Sandbox vs Live? =

**Sandbox** is for testing — no real money. **Live** is for real payments. Start in Sandbox, then switch to Live when you are ready.

= How does the customer get back to my site? =

Square sends them back automatically after payment. WooCommerce shoppers see the order confirmation page. Form visitors return to the same form with a success message.

= Can I sell subscriptions? =

Yes. Create plans in Square, then use **Subscription Plans** in this plugin to connect them to WooCommerce products, Contact Form 7 forms, or WPForms.

= Does this plugin charge an extra fee on payments? =

No. **Payments Square Connect** does not add a platform or application fee on top of your payments. You pay Square's normal card processing rates only.

= Is support available? =

Yes. **24/7 support available anytime** — open **Payments Square Connect → Support** for email, WhatsApp, or the [WordPress.org support forum](https://wordpress.org/support/plugin/payments-connect-square/).

= Is card data stored on my site? =

No. Customers enter payment details on **Square Hosted Checkout**. Your WordPress site does not store card numbers.

= Can I refund a WooCommerce Square order? =

Yes. Open a **paid** order that used **Payments Square Connect**, click **Refund**, and enter a full or partial amount. The plugin sends the refund to Square using the stored payment ID.

**When refunds work:** order is Processing or Completed, payment method is Payments Square Connect, and a Square payment ID is saved (from buyer return or webhook).

**Webhooks (recommended):** Copy the webhook URL from **Payments Square Connect → Connect** into the Square Developer Dashboard so payment IDs are saved even if the buyer closes the browser early.

**Troubleshooting:** "Square payment ID was not found" — wait for webhook or customer return. Refund failed — enable Debug Log and check **WooCommerce → Status → Logs** (source `shc4wc`). Partial refund rejected — try a lower amount.

= Can I issue a partial WooCommerce Square refund? =

Yes. Enter any amount up to the remaining refundable total on the WooCommerce order. Each refund is sent to Square separately.

= Why is the WooCommerce Square refund button missing or failing? =

The order must be **paid** with Payments Square Connect and have a **Square payment ID** saved (from buyer return or webhook). Pending or unpaid orders cannot be refunded through the gateway. Enable webhooks and Debug Log on the Connect screen if payment IDs are missing.

= How does Pay for Order work? =

Open an unpaid WooCommerce order. Under billing details, click **Email payment link to customer** or **Copy payment link**. The customer opens the link, clicks **Pay**, and completes payment on Square Hosted Checkout. The order moves to **Processing** after Square confirms payment. No card form appears on your order-pay page.

= Can I use Square payment links with Elementor or Beaver Builder? =

Yes. Search for **Square Payment Link** in the **Elementor** widget panel or in **Beaver Builder** modules (group **Payments Square Connect**). Set the amount and button label — same hosted checkout flow as the shortcode and Gutenberg block.

= Can I send a payment link for an unpaid WooCommerce order? =

Yes. Open the order in **WooCommerce → Orders** and click **Email payment link to customer** on the order screen (or copy the link). The customer pays on Square Hosted Checkout and returns to your site when done.

= Can I refund Contact Form 7, WPForms, or payment link payments from WooCommerce? =

No. Those payments are not WooCommerce orders. Refund them in the **Square Dashboard** (Transactions / Payments).

= Can I refund WooCommerce Square subscription renewals from wp-admin? =

Recurring charges billed by Square subscriptions should be refunded from the **Square Dashboard**. The initial WooCommerce subscription signup order can be refunded from wp-admin if it was a one-time hosted checkout payment with a stored Square payment ID.

= Does WooCommerce Square stock sync with Square catalog? =

When product **SKUs match** between WooCommerce and your Square catalog, paid **WooCommerce Square** orders can update **Square inventory** automatically. WooCommerce also reduces its own stock when payment is confirmed. Use the same SKU on both sides for the best results.

= Do Contact Form 7 and WPForms support Apple Pay, Google Pay, Cash App, and Afterpay? =

Yes. **One-time** payments from Contact Form 7 and WPForms use the same **Square Hosted Checkout** as **WooCommerce Square**. Enable **Apple Pay**, **Google Pay**, and **Cash App Pay** under **Payments Square Connect → Checkout Settings → Merchant settings** (Live mode). Enable **Afterpay/Clearpay** in your Square Dashboard. Buyers see whichever wallets you have turned on, plus card entry on Square's page.

Cash App Pay and Afterpay are **not** available for subscription signup on CF7 or WPForms forms.

= Do Fluent Forms work with Square wallets? =

Yes, with **Fluent Forms Pro**. Enable **Payments Square Connect** under **Fluent Forms → Global Settings → Payment → Payment Methods**, then add a **Payment Method** field to your form and select Square Hosted Checkout. Wallets follow the same **Checkout Settings** as **WooCommerce Square**.

== Screenshots ==

1. Connect your Square account, choose Sandbox or Live, and pick a location.
2. Checkout Settings: wallets, tipping, branding, and policies (Live mode only).
3. Subscription Plans: view Square plans and copy plan IDs.
4. WooCommerce Square: enable the gateway and set checkout title and description.
5. WooCommerce Square: refund a paid order from the order screen (full or partial refund sent to Square).
6. Contact Form 7: add Square payment tags to a form.
7. WPForms: Square Hosted Checkout field and Payments Square Connect panel.
8. Square Hosted Checkout: product names and totals shown on Square's payment page.
9. Get started onboarding wizard: connect Square, location, and WooCommerce gateway.

== Upgrade Notice ==

= 1.3.11 =
Adds optional AI setup assistant (your OpenAI key), admin REST routes, and developer hooks for automation.

= 1.3.10 =
Readme only — fixes plugin directory Description truncation warning.

= 1.3.9 =
New setup wizard (**Get started**), Pay for Order email links, Elementor and Beaver Builder payment widgets, and onboarding improvements. Update recommended for all merchants.

== Changelog ==

= 1.3.11 =
* **AI setup assistant** — optional OpenAI-powered troubleshooting on **Get started** (merchant API key on connection settings; no card or Square token data sent).
* **REST API** — `shc4wc/v1/status`, order payment URL, and send payment link email endpoints for admins and automation.
* **Developer hooks** — `shc4wc_square_connected`, `shc4wc_square_disconnected`, `shc4wc_pay_for_order_email_sent`, `shc4wc_checkout_redirect_to_square`, `shc4wc_payment_link_button_atts`, `shc4wc_rest_status`, `shc4wc_ai_troubleshoot_context`.

= 1.3.10 =
* **Readme** — shortened Description section to meet WordPress.org 2,500-word limit; refund and Pay for Order details expanded in FAQ.

= 1.3.9 =
* **Onboarding screen** — **Get started** setup wizard after activation: choose Sandbox/Live, connect Square, pick a location, enable WooCommerce gateway in one click, and open shop/checkout for a test order.
* **Setup progress** — progress bar and step checklist; **Finish setup** or **Skip setup for now**; OAuth returns to the wizard until setup is complete.
* **Admin notice** — prompts merchants to open **Get started** when Square is not connected yet.
* **Onboarding URL fix** — correct admin URL (`admin.php?page=…`) and redirect if an old pretty URL is used.

= 1.3.8 =
* **Elementor** — **Square Payment Link** widget (amount, button label, description, currency) for drag-and-drop Pay Now buttons on Elementor pages.
* **Beaver Builder** — **Square Payment Link** module under **Payments Square Connect** with the same settings as the shortcode and Gutenberg block.
* **Page builders** — both use the existing hosted checkout flow (Square page, return to your site with thank-you message).
* **Documentation** — README steps for Elementor and Beaver Builder.

= 1.3.7 =
* **Pay for Order / invoice link** — unpaid WooCommerce orders get a **Square payment link (Pay for Order)** panel on the order edit screen.
* **Copy payment link** — one-click copy of the customer **order-pay** URL (secured with order key).
* **Email payment link to customer** — sends the payment link from WordPress (`wp_mail`) in one click; shows billing email and adds an order note.
* **Order actions** — **Email Square payment link to customer** also available in the Order actions dropdown.
* **Hosted checkout on order-pay** — no on-site card form; customer pays on Square Hosted Checkout (avoids typical on-site Square **EMPTY_VALUE** errors).
* **Documentation** — README Pay for Order flow, FAQ, and comparison section updates.

= 1.3.6 =
* **Documentation** — README SEO and guides: **WooCommerce Square** headings, expanded refund documentation (step-by-step, webhooks, sandbox, troubleshooting), updated short description, and **How this plugin compares** (hosted checkout vs typical on-site and sync-heavy Square plugins).

= 1.3.5 =
* **WooCommerce refunds** — refund paid orders from the WooCommerce order screen (full or partial); refunds are sent to Square using the stored payment ID.

= 1.3.4 =
* **Gutenberg block** — **Square Payment Link** block now appears in the block inserter (title, category, icon, and keywords were missing).

= 1.3.3 =
* **WooCommerce checkout** — orders stay **Pending** when customers are redirected to Square Hosted Checkout; they move to **Processing** only after Square confirms payment (fixes abandoned checkouts showing as Processing too early).
* **Webhooks** — Square payment-completed webhooks now update orders that are still **Pending** after redirect.

= 1.3.2 =
* **Fluent Forms Pro** — Square Hosted Checkout payment method using your existing Square connection.
* **Payment link button** — `[square_payment_link]` shortcode and **Square Payment Link** Gutenberg block for pages and posts without WooCommerce or a form plugin.
* **Documentation** — README updates for wallets, Fluent Forms, payment links, and Gutenberg usage.

= 1.3.1 =
* **Cash App Pay & Afterpay** — payment links now pass `accepted_payment_methods` (Cash App Pay and Afterpay/Clearpay) per Square Checkout API requirements so enabled wallets appear on hosted checkout.

= 1.3.0 =
* **WPForms** — Square Hosted Checkout field, Payments Square Connect panel, one-time payments and subscription signup.
* **24/7 support** — help available anytime via Support page (email, WhatsApp, forum).

= 1.2.x (1.2.0 – 1.2.2) =
* Automatic Square OAuth token renewal; connect screen shows last renewal time.
* WooCommerce SKU catalog matching and Square inventory sync on paid orders.
* Documentation and plugin listing improvements.

= 1.1.x (1.1.0 – 1.1.9) =
* Admin menu: Connect, Checkout Settings (Beta), Subscription Plans, Support.
* Subscriptions for WooCommerce and Contact Form 7; checkout customization on Square hosted pages.
* WooCommerce itemized checkout lines; connection, Cash App Pay, and checkout settings fixes.

= 1.0.x (1.0.0 – 1.0.9) =
* Initial release: Square Hosted Checkout for WooCommerce and Contact Form 7, one shared Square connection.
* OAuth reliability, site URL change handling, and connection setup improvements.
