Integrating Square
Auth: OAuth 2.0 · Partner program: not required · Setup time: about 15 minutes · Last verified: 2026-05-15
Square Payments + Subscriptions + Invoicing across in-person POS and online checkout.
Auth model
Section titled “Auth model”OAuth 2.0 (oauth2). Authorisation-code flow at https://connect.squareup.com/oauth2/authorize, exchange at /oauth2/token. Returns a short-lived access token (typically 30 days) plus a refresh token.
Configure in admin
Section titled “Configure in admin”- Create an application at https://developer.squareup.com/apps
- Note
Application ID(client ID) and Production / Sandbox Application Secret (client secret). Add your redirect URI. - Open
/platforms→ Payments → Square → Configure and submitclientId,clientSecret, and the matchingredirectUri.
Required scopes
Section titled “Required scopes”Defaults requested by the adapter:
PAYMENTS_READ PAYMENTS_WRITECUSTOMERS_READ CUSTOMERS_WRITEINVOICES_READ INVOICES_WRITESUBSCRIPTIONS_READ SUBSCRIPTIONS_WRITEMERCHANT_PROFILE_READOverride on a per-installation basis through the Connect Link’s scope-group dropdown if you need a stricter set.
Webhooks
Section titled “Webhooks”Set up at Webhooks in the developer dashboard. Subscribe to payment.*, refund.*, customer.*, invoice.*, subscription.*, and dispute.*. Square signs deliveries with HMAC-SHA-256 over the URL + raw body using the subscription’s signature key.
Quirks
Section titled “Quirks”- Idempotency keys required on every write. The adapter generates a UUIDv4 per request via
node:crypto.randomUUID(). Pass a custom one throughmetadata.idempotencyKeyif you need cross-call idempotency. - Square-Version header is pinned to
2024-09-19. Bump inclient.tsafter re-testing. - POS-only resources (Terminal, Bookings, Loyalty) are not covered by this adapter.
References
Section titled “References”- Square API reference: https://developer.squareup.com/reference/square/
- Developer docs (OAuth + Webhooks guides linked from the docs index): https://developer.squareup.com/docs/square-get-started
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.