Square

The Square plugin (plg_solidshoppayment_square) lets shoppers pay on Square’s hosted checkout page. When a shopper places an order and chooses Square, Solidshop sends the order to Square as a payment link and takes the shopper there. They pay with the methods Square offers your account on that page, and Square sends them back to your store’s order confirmation. The money goes into your own Square account. Card details are entered on Square’s page and never reach your site.

The plugin talks to Square from your server with your access token, and checks each payment against Square’s own record before it marks an order paid. See the Square extension page for the overview.

Requirements

  • Joomla 6.x or later
  • PHP 8.4 or later
  • Solidshop 1.8.0 or later — the release that asks the payment plugin how the payment went when the shopper comes back. The installer refuses an older core, so update Solidshop first.
  • A Square account, and an application in Square’s Developer Console for the credentials
  • A public HTTPS address for your site, so Square can send its webhook. A site on localhost still records a payment when the shopper comes back from Square, but receives no webhooks

Installation

Download the plugin

Download plg_solidshoppayment_square.zip from the Downloads page while your subscription is active. Updates arrive through the Joomla updater.

Install via the Extension Manager

In System → Install → Extensions, drop the ZIP into the upload area. The Square PHP SDK ships inside the plugin, so there is no Composer step.

Enable the plugin

Go to System → Manage → Plugins, filter by the solidshoppayment type and enable Solidshop Payment - Square. The plugin is disabled after install: until you enable it, the store screen has no Square settings, so Square can’t be offered at checkout, and no webhook can be registered or answered.

Get your Square credentials

The plugin needs two values for each environment: an access token and a location ID. Square keeps a Sandbox for testing and Production for real payments, each with its own token and locations, and the store holds both pairs at once.

Open your application in the Developer Console

Sign in at developer.squareup.com with the Square account that should receive the payments, and open your application — or create one; any name will do.

Copy the access tokens

On the application’s Credentials page, switch between Sandbox and Production at the top and copy the access token shown for each. Treat it like a password: it opens your Square account to whoever has it.

Copy the location IDs

Open the application’s Locations page and copy the ID of the location your online sales belong to, once for the sandbox and once for production. Square records each order against that location, and charges in that location’s currency — see Currency.

Configure the plugin

Square settings belong to a store, not to the plugin: each store keeps its own credentials and its own webhook. Today the storefront takes payments through the master store, so set Square up there.

Open your store’s Payments tab

Go to Solidshop → Configuration → Stores, open the store and choose the Payments tab. Expand Square checkout and set Enable Square to Yes. The rest of the settings appear below it.

Pick sandbox or production

Test mode defaults to Yes, which sends payments to Square’s sandbox. Leave it on while you test; set it to No to take real payments. The switch also decides which pair of fields shows: the sandbox pair while it is on, the production pair while it is off. Both pairs are kept, so switching back and forth loses nothing.

Paste your credentials

Fill in Location ID and Access token for the mode you are in. Both are required for that mode while Square is on: the store won’t save without them (Field required: Location ID). The other mode’s pair can stay empty until you need it.

Optional — set a surcharge

To pass Square’s processing cost on to the shopper, enter a flat amount in Surcharge fee, in the store’s currency. It is added to the order as a Payment fee line when the shopper picks Square. Leave it empty or at 0 to pay the cost yourself.

Save the store

Saving registers the store’s webhook with Square and fills in the two read-only fields — see The webhook. Watch for the message the save shows.

Setting Default What it does
Enable Square No Offers Square at this store’s checkout.
Test mode Yes Yes uses Square’s sandbox and the sandbox fields; No uses production and the production fields.
Location ID Empty The Square location orders are booked to. Required for the active mode.
Access token Empty Your application’s access token for the active mode. Required for that mode.
Webhook Signature Key Read only Filled in when the store is saved: the key Square signs this store’s payment updates with.
Webhook URL Read only Filled in when the store is saved: where Square sends this store’s payment updates.
Surcharge fee Empty A flat amount added to the order when the shopper pays with Square.

The dashboard’s Store setup checklist counts Square towards Enable a payment method once the active mode has its location ID and access token, and its Switch payments to live mode step stays open while Test mode is on.

The webhook

Square reports each payment to your site through a webhook. The plugin uses it to record a payment whose shopper never comes back to your store — one who closes the tab after paying, say. You don’t set it up in Square yourself: the store does it when you save.

How it registers itself

When you save a store that has Square on and a location ID and access token for the active mode, Solidshop asks Square for the webhook subscriptions of the application your access token belongs to. If one already sends to this store’s address, it is reused; otherwise one is created, named Solidshop Square Webhook Subscription, for Square’s payment.updated event. The store then keeps the subscription’s signature key and address in Webhook Signature Key and Webhook URL, and the save says:

  • “Square webhook registered: Square sends this store’s payment updates to …” followed by the address.

A later save that finds the same key and address changes nothing and shows no message. The sandbox and production modes keep a key and address each, and a save registers the mode Test mode is set to, so save once in each mode.

Save from your site’s public address. The webhook address is built from the address you are using the administrator at when you save. Sign in at the site’s public https:// address, not a local, staging or http:// one: Square sends webhooks only to HTTPS, and it signs each one with the exact address it was registered with.

When the save can’t register it

A store always saves. Registering the webhook never stops the save; when it fails, the rest of what you changed is kept and you see a warning instead:

  • “The store was saved, but its Square webhook could not be registered: …” — followed by Square’s own reason. Most often the access token is wrong for the mode (a sandbox token with Test mode on No, or the other way round), or Square couldn’t be reached. Fix it and save again. A wrong token shows up here before any shopper meets it. A wrong location ID doesn’t: it shows only when a shopper checks out, so place a test order after changing it.
  • “Square can’t send payment updates to a site on localhost, so no webhook was registered. A Square payment is still recorded when the shopper comes back to the store.” — shown on localhost, 127.0.0.1 and *.localhost addresses. Nothing is registered; payments are recorded on the shopper’s return only.

A store you are creating gets its webhook on its second save: the first save creates the store. The two read-only fields stay empty until a save registers the webhook.

Save again after a change

Save the store again, in the mode concerned, whenever:

  • you change the access token — a token from another application has subscriptions of its own, and the new application needs one;
  • you move the site to another address: a new domain, www or not, http to https;
  • you delete the subscription in the Developer Console, or replace its signature key there.

The save registers the new address or picks up the new key. A subscription that still sends to an old address, or from an application you no longer use, keeps sending until you delete it: open the application in the Developer Console and remove it under Webhooks. Switching Square off on a store leaves its subscription in Square as well, and the store keeps recording the payments it reports.

What the shopper sees

  1. At checkout the shopper chooses Square checkout and places the order. Solidshop creates the order with the store’s starting payment status — Pending unless you changed it.
  2. The browser goes to Square’s checkout page, which lists the order’s lines and total. The page offers no tip.
  3. The shopper pays there, with a card or any other method Square offers your account on that page. Which methods appear is up to Square and your account’s settings there.
  4. Square sends the shopper back to your store, which checks the payment with Square and shows the order confirmation.

What the Square order contains

The order reaches Square itemised, and adds up to the order’s total in Solidshop:

Line What it holds
Each product The product’s name, its variant as Square’s variation name, the quantity and the unit price.
Shipping The order’s shipping, less any shipping discount.
Payment fee The store’s Surcharge fee for Square.
Tax The order’s tax, on a store whose prices leave tax out. Where prices include tax, the product lines already carry it and there is no tax line.
Discount The order’s discount, taken off the whole order.
Rounding The cent or so the lines fall short of the order total by, when a price has more decimals than the currency. When the lines come to more than the total instead, the difference goes on the Discount line, which then shows even on an order without a discount.

A shipping, fee, tax or discount line with nothing on it is left out. The line names are in the language the shopper checked out in. The shopper pays the order’s total to the cent, and the Square order carries the Solidshop order reference as its reference ID.

How a payment is confirmed

A Square payment is recorded in one of two ways, whichever comes first. Either way the plugin goes by Square’s record of the payment, never by the browser.

When the shopper comes back

The return address carries a token for the order, but coming back only proves the browser was sent back. Before it shows anything, the plugin asks Square for the Square order and its payments:

  • A completed payment — the order is recorded as Paid and the confirmation page shows a paid order.
  • A payment Square is still processing — the confirmation page shows the order as it stands, and the webhook records the payment when Square completes it.
  • Only failed or cancelled attempts — the order’s payment status is set to Voided and the shopper is back at the checkout with their cart and the message “Payment could not be processed for order … Please try again or choose a different payment method.” No confirmation e-mail goes out.
  • No payment yet — the order keeps its status, and the webhook settles it.

This is also how a site Square can’t reach, such as one on localhost, records its payments.

By webhook

Square sends a payment.updated event for every payment in your account. The plugin checks its signature against the key and address of the mode the store is in (its Test mode setting), matches the payment to one of this store’s Square orders, and records it once Square reports it completed. This covers the shopper who pays but never comes back.

The rules either way

  • A payment for less than the order total is recorded as Partially paid.
  • A declined card changes nothing: the shopper can try another card on the same Square page, and the order keeps its status until a payment completes.
  • Payments that are not this store’s — sales on your Square devices, another site or store on the same Square account — are acknowledged, so Square stops sending them, and ignored.
  • Once an order has received its money (Paid, Partially paid, Partially refunded or Refunded), no later update from Square changes it. A repeated webhook, or the update Square sends after a refund, never sets an order back to Paid.
  • A payment Square reports in another currency than the order’s is not recorded — see Currency.
  • A shopper who leaves Square’s page without paying sends nothing back. The order keeps its starting status and the cart stays theirs, so they can check out again.

On the order

Open the order in Solidshop → Sales → Orders to see what the plugin recorded:

  • Payment method reads Square checkout.
  • Transaction ID holds the Square order ID from the moment the order is sent to Square, and the Square payment ID once the payment is recorded. To find an order from a Square payment, search the orders list for TXN: followed by the payment ID.
  • Total paid is the amount Square took.
  • The Activity Timeline gets one entry per payment, with the Square payment ID under it: “Payment of … confirmed by Square” when it was recorded on the shopper’s return, “… confirmed by Square webhook” when the webhook recorded it. A payment for less than the order total reads “Partial payment of … recorded by Square webhook” instead.

The order confirmation e-mail is queued when the payment is recorded, or when the shopper comes back from Square, and goes out with your e-mail queue. An order whose payment failed gets none.

The plugin logs each step — the payment link it made, each payment it recorded, each webhook it rejected or ignored, each webhook registration — to solidshoppayment_square.php in your Joomla log folder (System → Global Configuration → System → Path to Log Folder, administrator/logs by default). Entries about an order name it as Order # followed by its ID.

Currency

Square charges in the currency of the location the order is booked to. The plugin sends the order in your store’s currency, without converting it, so make the two the same. If they differ, Square refuses to create the checkout page: the shopper sees “Payment could not be processed for order …” and the order’s payment status is set to Voided. A currency the shopper picks in the storefront’s currency switcher changes only the prices they see; the order is placed in the store’s currency.

A payment Square reports in any other currency than the order’s is not recorded: the plugin writes an error to its log and leaves the order as it is.

Decimals. Amounts go to Square in the currency’s smallest unit, worked out from Digits after the decimal point on the currency in Solidshop → Localization → Currencies. Keep it at the currency’s own number of decimals — 2 for USD, EUR, GBP, CAD and AUD, 0 for JPY — or Square is sent an amount a hundred times too large or too small.

Refunds

The plugin doesn’t refund from Solidshop, and a Square order has no Refund action on its order page. Refund in Square, then bring the order in line:

  1. In the Square Dashboard, open Transactions, choose the payment and issue the refund, in full or in part.
  2. In Solidshop → Sales → Orders, open the order, click its payment status at the top of the page and choose Refunded or Partially refunded. Setting Refunded returns the order’s stock, as it does for any order — see Orders.

Square does report the refund to the webhook, but the plugin leaves an order that has received its money as it is, so the order changes only when you change it.

Test in the sandbox

Set the store to sandbox

With Test mode on Yes, fill in the sandbox Location ID and Access token and save the store from its public address. Check for the Square webhook registered message; on a local site you get the localhost warning instead, and the test runs without the webhook.

Place a test order

On your storefront, check out with Square checkout. Square’s sandbox checkout page offers a test payment instead of asking for a real card; Square’s sandbox test values list cards to try as well. Complete the payment and Square sends you back to the order confirmation.

Check the order

In Solidshop → Sales → Orders, the order should read Paid, with Square checkout as its payment method, the Square payment ID as its Transaction ID, and a Payment of … confirmed by Square entry on its Activity Timeline (… confirmed by Square webhook if the webhook got there first). Compare the lines with the Square order in your sandbox test account’s dashboard, which the Developer Console opens from Sandbox test accounts.

Test the lines that matter to you. Run one order with a discount, shipping and, if you set one, the surcharge, and on a store whose prices leave tax out, one with tax. Each should appear on Square’s page as its own line, and the total should match the order in Solidshop.

Going live

  1. Set Test mode to No on the store’s Payments tab.
  2. Fill in the production Location ID and Access token.
  3. Save the store from its public https:// address and check for the Square webhook registered message. The production Webhook Signature Key and Webhook URL fill in; the sandbox webhook doesn’t carry over. Delete the sandbox subscription in the Developer Console once you no longer test: its events now get a 401.
  4. Place one low-value real order, then refund it in the Square Dashboard and set the order to Refunded.
  5. Check the dashboard’s Store setup checklist: Switch payments to live mode ticks once no enabled method is left in test mode.

Several stores

Every Square setting belongs to the store it is saved on. Each store has its own sandbox and production credentials, its own surcharge, and its own webhook, whose address carries the store’s ID. Two stores can use two Square accounts, or share one: a store’s webhook records only that store’s orders and ignores the rest. Today the storefront takes payments through the master store, so that is the store to set Square up on.

Troubleshooting

Square doesn’t appear at checkout

  • Check that Solidshop Payment - Square is enabled in System → Manage → Plugins.
  • Check that Enable Square is Yes on the store’s Payments tab, and that the store was saved.
  • Check that Square is set up on the master store: the checkout offers the master store’s payment methods.
  • If you can’t see the Payments tab, your user group lacks the Manage payment permission.

The save shows a webhook warning

  • “… could not be registered: …” — read Square’s reason after the colon. An authorisation error means the access token is wrong for the mode Test mode is set to. Fix it and save again.
  • The localhost warning is expected on a local site. To test the webhook, use a copy of the site at a public HTTPS address.

Checkout says “Payment could not be processed” and the payment status is Voided

  • Square refused to create its checkout page. Check that the access token and the location ID belong to the same Square account and the same mode, and that the location is active.
  • Check that the store’s currency is the location’s currency, and its decimals — see Currency.

Square’s webhook gets a 401

  • The log reads “Square webhook rejected — invalid signature for …”. Square signs each event with the subscription’s key and the address it was registered with; one of them no longer matches the store — the site moved, http became https, the key was replaced, or an old subscription still sends here.
  • The event comes from the other mode. The store checks only the key of the mode Test mode is set to, so once you go live the sandbox subscription’s events get a 401. Delete the sandbox subscription when you no longer test.
  • Save the store again from its public address, in the mode you use, and delete subscriptions you no longer use in the Developer Console.
  • A 404 with “Square webhook rejected — store #… not found or without Square settings” means the subscription sends to a store that no longer exists, or one that never had Square set up. Delete that subscription.

Orders stay Pending

  • Most often the shopper left Square’s page without paying. There is nothing to record; cancel the order when you tidy up.
  • If the payment shows in the Square Dashboard, the shopper didn’t come back and the webhook hasn’t reached the store. Check that the store’s Webhook URL is filled in for the mode you use, and look in the log for rejected webhooks. On localhost no webhook arrives; set the order’s payment status yourself.
  • A log line ending in “not the order currency … — not recorded” means Square took the payment in another currency — see Currency.

A refund in Square didn’t change the order

That is expected: set the order’s payment status yourself, as described under Refunds.

The confirmation e-mail doesn’t arrive

The e-mail is sent by Solidshop’s e-mail queue. If no e-mails go out, the scheduler task is the most likely cause — see Set up the email queue in the installation guide.