square-api-reference

Use when working with Square API for payments, orders, customers, catalog, webhooks, or OAuth. Also use when setting up Square authentication, handling payment errors, or switching from the legacy Square SDK.

Model	Source
sonnet	pack: payments

Full Reference

┏━ 🔧 square-api-reference ━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Use when working with Square API for payments,… ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Square API

Version: 2026-01-22 | Production: https://connect.squareup.com | Sandbox: https://connect.squareupsandbox.com

Quick Reference

Item	Value
Current API Version	2026-01-22
Auth	Authorization: Bearer ACCESS_TOKEN (server-side only)
Node.js	npm install square (v40+) — requires BigInt for money fields
Python	pip install squareup (v42+) — Pydantic response models

Reference Index

Route to the relevant file based on the task:

I want to…	File
SDK install, versioning, environments, migration from legacy	reference/sdk-setup.md
Access tokens, OAuth 2.0, PKCE, scopes, client init	reference/authentication.md
Create/cancel/refund payments, idempotency, fees	reference/payments.md
Create orders, pay orders, order states	reference/orders.md
Customer profiles, cards on file, list/charge saved cards	reference/customers.md
Catalog items, variations, categories, upsert, search	reference/catalog.md
Webhook signature verification, event types, best practices	reference/webhooks.md
Error categories, HTTP codes, error handling pattern, rate limits, backoff	reference/errors-and-limits.md
Sandbox setup, test nonces, Web Payments SDK, local webhook testing	reference/testing.md
API version history, SDK rewrite migration guide	reference/changelog.md

Usage: Read the reference file matching your current task from the index above. Each file is self-contained with code examples and inline gotchas.

Critical Gotchas

Gotcha	Detail
Node.js money fields	Require BigInt(100) — plain integers throw
Python responses	Pydantic models — use .attribute, not ['key']
Python errors	try/except ApiError — not response.is_error()
Webhook body parsing	Must use raw body parser — express.raw() not express.json()
Signature comparison	Use hmac.compare_digest / timingSafeEqual — not ==
Sandbox vs production	Credentials are completely separate — no cross-environment tokens
Legacy SDK paths	square/legacy and square_legacy deprecated — migrate now