Getting started

Core Features

Store Management

Payments

Developer

Square

Square is connected through Milo Payments and accepts credit and debit card payments via Square’s Web Payments SDK. It is particularly useful when you already use Square for in-person sales and want to reuse the same processing account online.

Key facts

  • Gateway ID: milo_square.
  • Method title at checkout: Square.
  • Built on Square’s Web Payments SDK for card input, and the Square Payments API (via the connect server proxy) for processing.
  • Connected via OAuth through connect.milosubscriptions.com. No access token to copy.
  • Recurring renewals use Square’s cards-on-file stored against the Square customer record.
  • A 1% application fee is added on top of Square’s standard processing fees on live transactions.

Connecting Square

  1. Go to Milo Subscriptions → Payments.
  2. Click the Square card, then click Connect with Square in the header.
  3. You are redirected to Square to authorize the connection.
  4. After authorizing, you are redirected back to your site. The card updates to CONNECTED and shows your Square merchant ID.

The connection stores four credentials internally:

  • Merchant ID: your Square account identifier.
  • Application ID: used by the Web Payments SDK in the browser.
  • Location ID: the Square location payments are attributed to. Defaults to your primary location.
  • Connected at: timestamp of the last successful connection.

Gateway detail page

Once connected, the Square detail page shows two sections:

Connection

  • Account: your Square merchant ID.
  • Mode: Test / Sandbox or Live.

Settings

  • Enable at checkout: show Square as a payment option during WooCommerce checkout.
  • Test / Sandbox mode: process test payments using Square’s sandbox environment.

A Disconnect button lives in the page header. Disconnecting revokes the OAuth connection and clears stored credentials.

Checkout experience

When Square is enabled, customers see a card input rendered by Square’s Web Payments SDK. The input handles:

  • Client-side validation.
  • Tokenizing the card into a single-use payment nonce.
  • Generating a card-on-file when the customer is buying a subscription, so the card can be used for future renewals.

Square’s card form is hosted inside an iframe served by Square, which keeps your site out of PCI scope for cardholder data.

Supported features

The Square gateway declares support for:

  • Products
  • Refunds
  • Tokenization
  • Subscriptions: cancellation, suspension, reactivation, amount changes, date changes, and payment method change (by both admin and customer) when Milo Subscriptions is active.

How renewals work

On the first subscription purchase, Milo Payments:

  1. Looks up or creates a Square customer record for the buyer and stores the customer ID as:
  • _milo_square_customer_id_{merchant_id} on the WordPress user (scoped by Square merchant).
  • _milo_square_customer_id on the subscription.
  1. Saves the tokenized card as a card-on-file on that Square customer, storing the card ID as _milo_square_card_id on the subscription.
  2. Records the successful Square payment ID on the order as _milo_square_payment_id.

On each renewal:

  1. Milo Payments looks up the customer ID and card ID on the subscription.
  2. It calls the Square Payments API with source_id = card_id and customer_id, charging the saved card on file.
  3. On success, the renewal order is marked Completed and the Square payment ID is stored on the renewal order.
  4. If either the customer ID or card ID is missing, the renewal fails and the customer is asked to add a new payment method.

Sandbox mode

Toggle Test / Sandbox mode on to route through Square’s sandbox. You will need a sandbox merchant account created from the Square Developer Dashboard. Square provides a set of test card numbers, which work the same way as Stripe’s test cards (typed into the card form while in sandbox mode).

Turn sandbox mode off only after you have:

  • Connected a live Square account.
  • Completed one live purchase successfully.
  • Run a successful test renewal from a subscription.

Application fee

On live transactions, Milo Payments adds a 1% application fee collected by the connect server proxy. This appears alongside Square’s standard processing fees on your Square dashboard transactions. No fee applies in sandbox mode.

Disconnecting

From Milo Subscriptions → Payments → Square, click Disconnect in the header. After confirming, Milo Payments:

  • Revokes the OAuth connection with Square.
  • Clears the stored credentials from wp_options.
  • Leaves active subscriptions in place but with invalid payment references. Renewals will fail until the customer adds a new payment method.

Troubleshooting

Square gateway does not show at checkout

Check:

  • Enable at checkout is on.
  • The Square Web Payments SDK is loading (look for network requests to js.squareup.com).
  • No content security policy or ad blocker is blocking Square’s domains.
  • There is no conflict with another Square plugin. Milo Payments shows an admin notice when it detects a duplicate.

Card input does not render

The Web Payments SDK needs the stored Application ID and Location ID to initialize. If you recently reconnected and one of these is missing, disconnect and reconnect to refresh the credentials.

Renewals fail with a card error

Check the subscription’s meta for both _milo_square_customer_id and _milo_square_card_id. If either is missing, the customer must add a new payment method through their My Account page. Most failures are caused by cards being closed, lost, or expired on Square’s side.

I use multiple Square locations

The connection stores a single Location ID. Payments route through that location. Switching locations requires disconnecting and reconnecting with the new location selected, which also invalidates existing cards on file. For multi-location setups that need separate revenue tracking, consider using a separate Square account per store.

A refund is not showing in Square

Refunds initiated from WooCommerce are sent to the Square Payments API using the stored _milo_square_payment_id. If the payment ID is missing from the order (common for orders created outside the normal checkout flow), refund from the Square dashboard directly and mark the WooCommerce order as refunded manually.

Next steps

  • Payments overview: compare Square with Stripe, PayPal, and Mollie.
  • Stripe: card payments with broad international support.
  • PayPal: add PayPal, Venmo, and Pay Later.
  • Mollie: add European methods like iDEAL and Bancontact.