Square setup

Updated Oct 17, 2026 Payments

If you already take Square at a till, connecting the same Square account to TitanCart keeps online and in-person sales in one Square Dashboard, one deposit, one set of reports. The card form sits on your checkout page (Square’s own secure field), the card is charged when the order is placed — or only authorised, if you choose delayed capture, and charged when you capture it from the order — and refunds go back through Square from the order.

Edition note: Square is a TitanCart Pro gateway. TitanCart Lite ships Stripe, Cash on Delivery, Bank Transfer and Check.

1. Create a Square application

Sign in to the Square Developer Dashboard with the Square account that takes your payments.
Click + Create new application, name it (for example “TitanCart”), and open it.
At the top of the app page a toggle switches between Sandbox and Production. Leave it on Sandbox for now; every credential below exists in both and they are different values.

2. Collect three credentials

Application ID — on the app’s Credentials page. Sandbox IDs start with sandbox-sq0idb-, production ones with sq0idp-.
Access Token — same page, click Show. Keep it secret.
Location ID — under Locations in the app’s left menu. Pick the location online orders should book to; it starts with L. In the sandbox, the Developer Dashboard gives you a test location automatically.

3. Add Square in TitanCart

Go to Settings → Payment Gateways → + Add Payment Gateway.
On the General tab choose the Credit / Debit Card (Square) gateway, give it the name shoppers will see, an optional Description and Payment instructions, set Status to Active, save.
Reopen it; the Configure tab exists after the first save. Fill in:
- Application ID, Access Token, Location ID — from step 2.
- Sandbox / Test Mode — on by default; leave it on while testing.
- Capture Method — Auto-complete (charge immediately), the default, charges the card as the order is placed. Delayed capture (authorize, capture later) only reserves the amount and leaves the charge to you; see the note below.
Save and click Test Connection. It should say “Square connection successful! Found 1 location(s). You are connected to the SANDBOX environment (no real charges).” If it adds a warning that the Location ID was not found, the ID belongs to the other environment or another account.

Delayed capture. With Delayed capture (authorize, capture later) Square reserves the amount on the card and takes nothing. The order is placed On Hold with its stock reserved, the shopper is told their card has been authorised but not charged, and you get the usual new-order email. The money moves when you click Capture in the Payment panel on the order page, which also moves the order to Processing and sends the customer their confirmation; Void releases the hold and cancels the order instead. Square drops an authorisation that is not captured within 7 days, and TitanCart then cancels the order and returns its stock. Use it when you want to look an order over before taking the money — the full walk-through is Capturing and voiding authorised payments. Stores still on TitanCart 0.2.44 or earlier should keep Auto-complete: those versions had no capture step and treated an authorisation as a payment.

A Square row with the Access Token or Location ID empty shows a NEEDS SETUP pill in the gateway list and takes no payments.

4. Test with sandbox cards

On the storefront, add a product, go to checkout and choose the Square gateway: the card field appears on the page. Square’s sandbox accepts its published test cards:

4111 1111 1111 1111 — Visa, succeeds.
5105 1051 0510 5100 — Mastercard, succeeds.
4000 0000 0000 0002 — declined.
Expiry: any future date. CVV: 111. Postal code: 94103.

A successful card places the order as Processing, reduces stock, empties the cart, uses any coupon, issues any digital gift card and sends the confirmation and new-order emails. With Delayed capture the same card instead places the order On Hold with its stock reserved and the cart emptied, sends the shopper an “order received” email saying the card was authorised, sends you the new-order email, and waits for you to capture it — the coupon, gift card and confirmation follow the capture. A declined card shows Square’s message on the checkout page and nothing is placed. Your test payments appear in the sandbox Seller Dashboard, not your real one — see Finding your Square sandbox transactions.

5. Switch to production

Flip the Developer Dashboard toggle to Production and copy the production Application ID (sq0idp-), Access Token and the Location ID of the real location you sell from.
In TitanCart replace the three values on the Configure tab, untick Sandbox / Test Mode, save.
Click Test Connection: it should now say LIVE environment and find your real locations, with no Location ID warning.
Place one small real order and refund it from the order.

6. Refunds, saved cards, what Square does not do here

Refunds — refund a Square order from the order in Sales → Orders, in full or in part; TitanCart sends it to Square and records it. A refund made in the Square Dashboard instead is not reported back (there is no Square webhook), so start refunds from TitanCart.
Subscriptions — with the Subscriptions extension, Square keeps the card on file at the first payment and charges renewals. Subscription orders are always charged immediately whatever the Capture Method says. A subscription that starts later with nothing to pay today needs Stripe.
Not offered through this gateway: Cash App Pay, Afterpay / Clearpay, Apple Pay and Google Pay — the checkout shows Square’s card field only — and the 3-D Secure challenge (so a store selling into the UK or EU, where banks require it, should use Stripe).

How to verify on Square’s side

Every TitanCart payment reaches Square with the note “Order TC-…” (your order number). In production, open the Square Dashboard → Transactions, pick the location, and search the order number, amount or date; the transaction’s detail shows the card, Square’s fee and any refund. Sandbox payments live in the separate sandbox Seller Dashboard (how to open it). On TitanCart’s side, the order page’s Payment panel lists the payment, any refund or void, and Square’s payment id for each, so you can search Square by that id as well.

Troubleshooting

“Square authentication failed”. The Access Token is wrong, revoked, or from the other environment (a sandbox token with Sandbox / Test Mode off, or the reverse). Re-copy it from the matching toggle position and run Test Connection.
Test Connection warns the Location ID was not found. The ID is from the other environment or another Square account. Sandbox and production locations are different IDs.
The card field doesn’t appear at checkout. The Application ID or Location ID is empty on the Configure tab, or the gateway is Disabled.
The gateway shows NEEDS SETUP. The Access Token or Location ID is empty.
Card orders arrive On Hold with an amber “Authorised … — not yet charged” banner. Capture Method is on Delayed capture, and that is the feature working: capture or void each order from its Payment panel (Capturing and voiding authorised payments). Switch to Auto-complete if you would rather be paid at checkout.
Orders placed before TitanCart 0.2.45 say Processing but the money never arrived. Earlier versions treated a delayed-capture authorisation as a payment. The Payment panel lists those payments but offers no Capture for them: complete each one through Square before its 7 days run out, or ask the customer to pay again. Orders placed on 0.2.45 or later wait On Hold instead.
A real card was charged but the order isn’t there. Check Test Connection says LIVE, then find the payment in Square’s Transactions by amount and time; if Square has it and TitanCart does not, the order will be completed by Settings → General Settings → Order Automation’s hourly check when Square confirms it.