What we do
Tools
Industries
Department
How we workLet's talk →
Home/Square/Square API
Square

The Square API: Picking the Right Endpoints, Tokens and Webhooks for Your Build

Square's API lets your own software take payments, build orders, manage the item catalog and stock, drive a Square Terminal, and hear about changes through webhooks. You start in the Square Developer Console (formerly the Developer Dashboard) by creating an application, which gives you separate sandbox and production credentials. The harder part is picking the right pieces, so start there.

Which Square API does which job

You want to Use Watch for
Take a card payment on your own website The Web Payments SDK in the browser to tokenize the card, then the Payments API on your server Every create call needs an idempotency key. Reuse the same key when you retry, so a timeout never charges twice.
Charge for a cart with items, tax and discounts The Orders API, then pay the order A payment with no order behind it reaches Square's reports as an amount, without item detail.
Manage items, variations and prices The Catalog API Objects carry a version number. Send the current one on updates, or you'll overwrite someone's newer change.
Read or change stock counts The Inventory API Counts are per location, and changes are recorded as adjustments or physical counts, not a single number you overwrite.
Charge on a Square reader from your own software The Terminal API Needs a Square Terminal paired to your app with a device code. Steps below.
Find out when something changes Webhooks, plus the Events API to catch up on anything missed Duplicates and out-of-order delivery are normal. The pitfalls further down cover the usual causes.

Square personal access token or OAuth?

Personal access token

Your own Square account

  • Found on your application's credentials page in the Developer Console, with separate sandbox and production tokens.
  • Required for the Webhook Subscriptions API and the Events API. OAuth tokens aren't accepted there.
  • Full access to the account, so keep it on a server and rotate it if it ever leaks.
OAuth

Other sellers' accounts

  • Each seller authorizes the permissions your app asks for. The authorization code lasts five minutes and works once.
  • Access tokens expire after 30 days, so refresh them on a schedule.
  • Code-flow refresh tokens don't expire. PKCE refresh tokens are single-use and last 90 days. Pick one flow and stick to it.

For your own business, a personal access token on a server is enough. For an app other Square sellers connect, use OAuth and run a job that refreshes tokens well before day 30, because a lapsed token stops that seller's sync without warning.

Running a Square Terminal checkout from your own app

The Terminal API lets your software send the amount to a Square Terminal and get the result back, while Square handles the card.

  1. 1

    Create a device code

    Call POST /v2/devices/codes with the product type TERMINAL_API and the location. Square returns a short code.

  2. 2

    Pair the Terminal

    Sign in on the Terminal with that code. Square sends a device.code.paired webhook, or you can check the code, and you get the device ID to store.

  3. 3

    Send the checkout

    Call POST /v2/terminals/checkouts with the amount, the device ID and an idempotency key. The Terminal shows the amount to the customer.

    Watch for: timeouts. If your call times out, retry with the same idempotency key. A fresh key can create a second checkout.

  4. 4

    Wait for the result

    Listen for terminal.checkout.updated. A completed checkout carries the payment IDs. A cancelled one means no charge, so tell staff right away.

  5. 5

    Tie the payment to your order

    Store the payment ID against the order or ticket in your own system, so refunds and reports can find it later.

Square webhook mistakes that only show up in production

The signature never matches

How you'll know: Every notification fails verification, though the signature key is right.

Fix: Square signs the notification URL exactly as you registered it plus the raw request body, with HMAC-SHA256, in the x-square-hmacsha256-signature header. Verify before parsing the JSON, use the registered URL rather than the one your proxy rewrote, and compare in constant time.

The same event processed twice

How you'll know: A stock count drops twice, or a customer gets two emails.

Fix: Square can send a notification more than once. Store each event_id and skip any you've already handled.

An older update overwrites a newer one

How you'll know: Your copy of an order or count ends up in an earlier state.

Fix: Delivery order isn't guaranteed. Fetch the current object from the API before acting on an update, instead of trusting the payload's order.

A day of downtime, then nothing

How you'll know: Your endpoint was down, and some events never arrived after it came back.

Fix: Square retries for up to 24 hours with growing gaps, then discards the notification. Use the Events API to pull what you missed after an outage.

Sandbox works, production doesn't

How you'll know: Calls return AUTHENTICATION_ERROR with UNAUTHORIZED, or webhooks are blocked by your firewall.

Fix: Sandbox tokens only work against connect.squareupsandbox.com and production tokens against connect.squareup.com. Square publishes separate IP addresses for each environment, so allow the production set too.

After it works: the Square jobs nobody scoped

Square keeps its own register, online store and locations in step from one item library. It doesn't keep counts matching with Shopify, WooCommerce, an Amazon listing or a wholesale ERP. That sync has to read changes from both sides, decide which one wins, and not double-count a sale that shows up in both.

A Terminal on flaky Wi-Fi leaves a checkout in limbo. The integration needs to notice, retry safely with the same key, and tell the person at the counter whether the card was charged before they try again.

Then there's the money afterwards. Payouts, fees and refunds still have to reach the books. Square's official QuickBooks connector covers the basics, and our QuickBooks and Square guide explains what it leaves out. n-frames builds and runs these pieces on the Square API for businesses whose Square setup has to agree with everything else they sell through.

Questions people ask

What do I need to start building with the Square API?

A Square developer account and an application created in the Developer Console. The application gives you a sandbox access token to build and test with, and a separate production token for when you go live.

What's the difference between Square's sandbox and production credentials?

Sandbox credentials work against a test environment with test card details and a test location, so no real money moves. Production credentials move real money. The calls are the same, but the base URL differs, and a token used against the wrong environment is rejected.

What is the Square Terminal API?

It lets your own software send a checkout to a paired Square Terminal and get the result back. You build the point of sale screens, and Square's hardware handles the card.

Does Square support webhooks?

Yes. Add a webhook subscription to your application in the Developer Console, or through the Webhook Subscriptions API, and Square posts events such as payment, order and inventory changes to your URL. Verify each one with the signature header and expect the occasional duplicate.

Do I need a developer to integrate Square with my website or POS?

Not for Square Online or a supported e-commerce plugin. You do once you're calling the API directly, using the Terminal API, or keeping Square's catalog and stock in step with another system.

Does the Square API connect to QuickBooks automatically?

Not by itself. The API gives you the data, and something has to post it. There's an official connector between the two, covered in our QuickBooks and Square guide, along with where it falls short.

Which Square API version should I call?

Square uses date-based versions, sent in the Square-Version header. Without the header, calls use the default version set on your application, so pin one in your code and upgrade on purpose after reading the changelog.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.