Skip to main content
Use Square through Corsair: one client, typed API calls. Authentication is a Square access token, sent as a Bearer token: a personal access token or an OAuth token. An OAuth token is refreshed when it expires, and once more after Square answers a request with a 401; a missing token fails with a clear error instead of an empty Bearer. Square runs production and a sandbox as separate worlds, and a token only works in the one it came from. The plugin calls production by default; pass square({ environment: 'sandbox' }) to call connect.squareupsandbox.com with a sandbox token. Every request sends Square-Version: 2026-09-16. Inputs and answers use Square’s own snake_case field names, and a money amount is { amount, currency } with the amount in the currency’s smallest unit (cents for USD). Idempotency. Calls that create or change money, or that Square lets you repeat safely, take an idempotency_key: nine operations require one (payments.create, payments.update, payments.refund, payments.cancelByIdempotencyKey, orders.pay, cards.create, catalog.upsert, disputes.createEvidenceText and disputes.createEvidenceFile), and many more accept one. Input keys a schema does not list are dropped, so a misspelled optional idempotency_key (for example idempotencyKey) sends the call without a key: it is then not deduplicated and not retried after a server error. You supply the key; the plugin sends it unchanged and never makes one up. Reuse the same key to retry the same call: Square then returns the first result instead of acting twice, so a timed-out charge cannot charge a card twice. A new key is a new payment. If the response to payments.create was lost and you cannot tell whether it ran, payments.cancelByIdempotencyKey voids it by the same key. Operations that move money: payments.create, payments.update, payments.complete, payments.cancel, payments.cancelByIdempotencyKey, payments.refund, orders.pay, invoices.publish (it may charge the card on file) and disputes.accept. Their descriptions say so. payments.refund, payments.cancel, payments.cancelByIdempotencyKey and disputes.accept cannot be undone. Every operation that moves money is destructive, as are webhookSubscriptions.test (it sends an event to your URL), invoices.update, invoices.createAttachment and invoices.deleteAttachment (Square emails or texts the customer when the invoice’s delivery_method is EMAIL or SMS) and the deletes, so a permission policy can hold them for approval. Retries. A 429 is retried by Corsair’s HTTP layer, up to three times, waiting for Retry-After when Square sends one: Square rejected the request without running it, so this holds for every operation. After a 5xx or a dropped connection the first attempt may have run, so the plugin retries (twice, with backoff) only reads, including the read-only POST searches, and the nine operations that require an idempotency_key, with the same key. Every other write, including a PUT, a DELETE and a call whose optional key you passed, is not retried: check its state with a read before you repeat it, with the same key if it took one. A declined card (PAYMENT_METHOD_ERROR) is Square’s answer and is never retried. Errors. A failed call throws Corsair’s ApiError unchanged, with status, retryAfter and Square’s response as body. Its message is the HTTP status text; Square’s errors[] (category, code, detail, field) is in error.body.errors, and squareErrors(error) from @corsair-dev/square returns it typed. A call that got no response throws SquareNetworkError; its message and cause carry only the error name and system code (for example TypeError ECONNRESET), never the original text, which can quote the Authorization header. A token with a line break or control character is refused before anything is sent. Pagination. List and search operations take cursor and limit and return the next cursor; pass it back for the next page. It goes in the query string for GET lists and in the body for the POST searches. Files. disputes.createEvidenceFile and invoices.createAttachment take the file as base64 in file_base64, with an optional filename (default: attachment plus the extension of its type); the plugin sends it to Square as multipart. Not included yet: Square’s GraphQL endpoint, webhook triggers, and the other API families (bookings beyond the business profile, loyalty, gift cards, payouts, team, labor, terminal, subscriptions). What you get:
  • 123 typed API operations

Setup

1

Install

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

4

Connect a tenant

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.

Example API calls

List the seller’s locations
Create a customer
See the full list on the API page.

What’s next

API reference

Every square.api.* operation with input and output types.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.