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
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
- OAuth 2.0
Store the Square API key before the first call: More: API Key
pnpm corsair setup --plugin=square --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.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 locationsWhat’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.