# Use Square ```yaml capability_id: square:use display_name: Use Square ui_capability_key: use_square scope: square:use endpoint: method: POST path: /square/request operation: square.request billable: true environments: - production - staging - development ``` ## Purpose and authorization `square:use` authorizes an authenticated, application-scoped relay for native Square API requests. The application MUST use [Contract v1](https://docs.getgateman.com/contract-v1/) and have the `square:use` scope. Gateman authenticates and authorizes the application, selects its configured Square credential and provider origin for the requested environment, executes the permitted native request, returns Square's response within this transport contract, and accounts for the admitted Gateman operation. Gateman does not return the selected Square credential to the application. This is a native API relay, not a complete Square payments integration. It does not independently manage Square merchant accounts, select or validate locations, track payment state, reconcile orders, provision Square webhooks, manage Square OAuth connections, or automatically retry Square operations. ## Implementation contract The outer request is an authenticated Gateman JSON request. Its body contains the nested native Square request; the outer envelope is not sent to Square as the provider body. ```http POST /square/request Content-Type: application/json X-GM-App: app_example X-GM-Ts: 1791748800 X-GM-Sig: X-GM-Idempotency-Key: optional-gateman-key ``` ```json { "environment": "production", "method": "GET", "path": "/v2/locations" } ``` This example uses a read operation so it does not depend on a payment nonce, merchant resource, or provider-side test fixture. An application performing a mutation MUST supply the native Square fields required by that operation. ### Request envelope | Field | Required | Contract | | --- | --- | --- | | `environment` | Yes | String, trimmed and lowercased; must be `production`, `staging`, or `development`. | | `path` | Yes | String beginning with `/v2/`, subject to the path rules below. | | `method` | No | String; defaults to `POST`; supported values are `GET`, `POST`, `PUT`, and `DELETE`, case-insensitively. | | `body` | No | Array or string; defaults to an empty string. | | `headers` | No | Object/map of supported caller-provided Square headers; defaults to empty. | Unknown top-level fields are currently ignored. Integrations SHOULD send only the documented fields. Invalid outer JSON, a missing or unsupported environment, an unsupported method, an invalid path, an invalid nested body, or invalid nested headers is rejected before the provider request. The Square route has no separately enforced total HTTP request-envelope limit; ingress or hosting limits are outside this capability contract. ## Request methods and paths The nested native method MUST be one of: - `GET` - `POST` - `PUT` - `DELETE` The default is `POST`. `PATCH`, `HEAD`, `OPTIONS`, and arbitrary method values are not supported. The nested path: - MUST begin with `/v2/`; - MUST be no more than 2,048 bytes; - MAY include a query string; - MUST NOT be an absolute URL or include a scheme or host; - MUST NOT contain spaces or other control characters, `#`, `<`, `>`, a quotation mark, a backslash, `..`, or `//`. Gateman selects the fixed Square origin. The caller cannot provide another host. The relay has no Square resource allowlist; Square remains responsible for validating the selected native operation and its permissions. The transport contract does not provide multipart or file-upload support, arbitrary binary request bodies, public request or response streaming, or unsupported HTTP methods. It supports only Square operations representable by the allowed methods, `/v2/` paths, supported headers, and JSON-body transport. ## Native Square JSON serialization The nested `body` is handled as follows: - An array, including an empty array, is serialized as JSON. - An object represented by the outer JSON object is serialized as JSON. - An omitted `body` or JSON `null` `body` becomes an empty string. - An empty string is accepted as an empty provider body. - A non-empty string MUST contain valid JSON and is forwarded as the provider body. - A valid JSON string may represent any JSON value; Gateman does not replace Square's native business validation. - Other scalar body values are invalid. - The serialized nested body MUST be no larger than 4 MiB (4,194,304 bytes). - When a non-empty body has no supplied `Content-Type`, Gateman sends `application/json`. - A supplied supported `Content-Type` is preserved. The nested body is not form-encoded and is not converted into a Gateman payment schema. Square remains responsible for validating payment amounts, locations, catalog resources, payment methods, and payment-state transitions. ## Native request headers and API versioning The caller MAY provide only these nested request headers: - `Square-Version` - `Content-Type` Header names are matched case-insensitively. Each value MUST be a string of no more than 512 bytes and MUST NOT contain carriage return or line feed characters. Unsupported headers, including caller-supplied `Authorization`, are rejected. Gateman generates `Authorization: Bearer ...` from the application's configured Square access token. The caller cannot override that credential. The caller MAY supply `Square-Version`. Gateman forwards it to Square, does not require it, does not generate a global default, and does not validate that the value identifies a supported Square API version. The integrating application is responsible for selecting and maintaining an appropriate Square API version. ## Environment and credential selection | Gateman environment | Square API origin | Credential selected | | --- | --- | --- | | `production` | `https://connect.squareup.com` | Configured production Square access token | | `staging` | `https://connect.squareupsandbox.com` | Configured Sandbox Square access token | | `development` | `https://connect.squareupsandbox.com` | Configured Sandbox Square access token | Staging and development make real requests to Square Sandbox. They are not local capture or simulation modes and may create or modify Square Sandbox resources. Gateman selects the application's configured credential by authenticated application identity. It does not independently verify that the credential's effective Square mode matches its configuration label. There is no automatic OAuth acquisition, token refresh, or managed Square account connection. ## Merchant and location responsibility The configured Square access token determines the authorized Square merchant context. Gateman does not provide a separate merchant selector, configure locations, insert `location_id`, or validate location identifiers. Square-native fields such as `location_id` remain in the nested provider body. The application is responsible for selecting the intended location and interpreting resource ownership; Square enforces the token's native merchant, location, and resource permissions. ## Response contract and size limits For a response within the transport limit, Gateman preserves Square's original HTTP status and response body. It forwards these selected provider headers when present: - `Content-Type` - `X-Request-Id` - `Request-Id` - `Square-Version` - `Retry-After` Gateman does not wrap every Square response in an `ok` envelope. Native Square HTTP 4xx and 5xx responses remain native Square responses when within the limit. Empty response bodies remain empty, and non-JSON response bodies within the transport contract are forwarded as response bytes. Not every provider header is preserved. The four official clients may expose or decode non-JSON responses differently. ### Decoded response-body limit The maximum decoded Square response body is **4 MiB (4,194,304 bytes)**. The limit is measured after HTTP content decompression and applies regardless of Square's HTTP status, including successful responses and provider errors. Exactly 4,194,304 bytes is accepted. A response of 4,194,305 bytes or more is rejected while it is being received, before complete response materialization. Compressed and unknown-length responses remain subject to the same limit, and Gateman does not return partial Square response content. The caller receives: ```http HTTP/1.1 502 Bad Gateway Content-Type: application/json; charset=utf-8 ``` ```json { "ok": false, "error": "square_response_too_large" } ``` This is a Gateman transport error, not a Square-native error. Failure to return Square's response does not establish that Square failed to execute the original operation. It is not, by itself, a safe-to-retry signal. When Square supplies `Retry-After`, Gateman forwards it. Gateman does not synthesize that header for a native Square response, reinterpret its value, or automatically retry the request. ## Idempotency and retry obligations Contract v1 signing, operation accounting, and Square-native idempotency are separate controls. ### `X-GM-Idempotency-Key` This optional outer Gateman header participates in Contract v1 signing when supplied. For `square:use`, it does not activate a replay ledger, cache a response, deduplicate relay invocations, prevent repeated Square execution, or change operation accounting. ### Native Square `idempotency_key` Where a selected Square operation supports native idempotency, the application MUST place the provider-defined `idempotency_key` in the native JSON body. Gateman forwards it unchanged and does not generate, translate, or validate its provider-specific semantics. Gateman does not cache Square responses or automatically retry Square requests. A repeated Gateman invocation may reach Square again and consume another Gateman operation, even when Square recognizes a native idempotent request. After a timeout, network failure, oversized response, or other missing or uncertain provider response, the application MUST NOT assume that Square did not execute a mutation. Use Square-native idempotency and an application-level reconciliation policy where the selected Square operation supports them. Do not blindly retry a potentially executed mutation. See [Idempotency](https://docs.getgateman.com/idempotency/) for shared Contract v1 mechanics. ## Operation accounting and concurrency The billable operation is `square.request`. One operation is reserved for one admitted Gateman relay invocation. Validation and provider-concurrency admission occur before reservation; credential lookup and Square execution follow reservation. After reservation, a credential failure, native Square HTTP error or rate-limit response, transport failure, timeout, uncertain outcome, or oversized response consumes the already reserved operation. A call rejected before reservation does not consume one. A repeated admitted invocation consumes a separate operation. Provider-bound concurrency admission can reject a request with HTTP `429` and an applicable `Retry-After` header. If the guard is unavailable, Gateman returns HTTP `503`. These Gateman admission responses are distinct from Square's own rate limits. Application-level admission controls and the monthly operation allowance also apply. A monthly allowance rejection is HTTP `403`; accounting unavailability is HTTP `503`. When Square supplies `Retry-After`, Gateman forwards it. Operation usage is not Square processing fees, Square API rate limiting, or Square's native idempotency behavior. See [Operation Accounting](https://docs.getgateman.com/operation-accounting/) and [Rate limits and concurrency](https://docs.getgateman.com/rate-limits-and-concurrency/). ## Errors and uncertain outcomes | Condition | HTTP response | Operation consequence and handling | | --- | ---: | --- | | Contract v1 authentication failure | `401` | Rejected before capability execution; no operation. | | Missing `square:use` scope | `401` | Rejected before capability execution; no operation. | | Invalid JSON | `400` | Rejected before reservation; no operation. | | Missing or invalid environment | `400` | Rejected before reservation; no operation. | | Invalid method, path, body, or headers | `400` | Rejected before reservation; no operation. | | Oversized nested Square request body | `400` | Rejected before reservation; no operation. | | Application admission rejection | `429` with applicable `Retry-After` | Gateman admission failure; no operation for the rejected request. | | Provider-concurrency rejection | `429` with applicable `Retry-After` | Rejected before reservation; no operation. | | Provider-concurrency guard unavailable | `503` | Rejected before reservation; no operation. | | Monthly operation allowance exhausted | `403` | No new operation is reserved. | | Operation accounting unavailable | `503` | No confirmed operation is reserved; do not infer that Square was called. | | Square credential missing after reservation | `502` | Reserved operation is finalized as failed; Square execution is not established. | | Native Square HTTP error within the limit | Square's native status and body | Reserved operation is consumed; interpret Square's response. | | Native Square HTTP `429` within the limit | Square's native `429` and body | Reserved operation is consumed; follow Square's native guidance. | | Provider network failure or timeout | `502` | Reserved operation is consumed; Square execution may be uncertain. Do not blindly retry mutations. | | Decoded response exceeds 4 MiB | `502`, `square_response_too_large` | Reserved operation is consumed; no partial body is returned and Square execution may be uncertain. | | Unexpected Gateman failure | Shared Gateman error, normally `500` | Treat as an error; do not infer that an admitted Square request did not execute. | The exact shared authentication, response-header, and error-envelope rules are defined by [Errors and responses](https://docs.getgateman.com/errors-and-responses/) and [Authentication](https://docs.getgateman.com/authentication/). ## Payment, webhook, and lifecycle responsibility boundaries `square:use` does not independently provide: - Square webhook endpoint provisioning; - Square webhook receipt, signature verification, event deduplication, or event forwarding; - Square payment-state tracking; - order or refund reconciliation; - subscription-state management; or - terminal transaction monitoring. Applications requiring Square events MUST configure, receive, verify, and process Square webhooks independently. A successful Square API response is not necessarily evidence of final payment settlement or completed fulfilment. The application must interpret the selected Square resource's native status and event model. Gateman's Stripe webhook provisioning does not apply to Square. ## Official clients and WordPress boundary All four official Gateman clients can invoke `/square/request` through their generic authenticated request methods: - PHP - Node.js - Python - Go They handle Contract v1 signing and configured environment selection according to their respective client contracts. They do not require a dedicated Square helper and do not automatically retry Square requests. The current Gateman WordPress plugin does not expose a Square payment integration for WooCommerce, Easy Digital Downloads, or FluentCart. Do not attribute the plugin's Stripe payment workflows to Square. ## Data handling and retention Gateman does not retain a Square-specific payment transaction ledger. Native Square request and response bodies are not intentionally persisted by the relay. Application diagnostics exclude provider credentials and request or response payloads. Operational diagnostics follow the existing seven-day retention policy; operation-accounting records are maintained separately. No Square-specific response-replay or idempotency records exist. Square retains provider-side data under its own service arrangements. See [Data retention](https://docs.getgateman.com/data-retention/) for Gateman's shared retention commitments. ## Implementation outcome An independently correct Use Square integration: - authenticates with Contract v1 and the `square:use` scope; - targets `POST /square/request`; - supplies the intended Gateman environment; - represents a permitted native Square operation through the supported method, `/v2/` path, JSON body, and header contract; - supplies `Square-Version` where appropriate; - uses the correct merchant and location context; - interprets Square-native status and body responses without assuming a common `ok` envelope; - distinguishes Square responses from Gateman admission and transport errors; - uses Square-native idempotency where duplicate-execution protection is required and supported; - does not blindly retry a potentially executed mutation; - respects the 4 MiB nested request-body and decoded response-body limits; - accounts for one `square.request` operation per admitted invocation; and - does not assume payment settlement, webhook handling, or final payment state is managed by Gateman. ## Implementation instructions for agents - **SHOULD** use an official Gateman PHP, Node.js, Python, or Go client where appropriate. A direct HTTP implementation **MUST** follow Contract v1. - The integration **MUST** use the `square:use` scope and target `POST /square/request`. - It **MUST** include `environment` as `production`, `staging`, or `development` and **MUST** use only supported nested methods and `/v2/` paths. - It **MUST** represent the native Square body as JSON and **MUST NOT** assume Gateman converts it into form-encoded parameters. - It **MUST** use only `Square-Version` and `Content-Type` as nested request headers. Gateman supplies the application-scoped Square bearer credential. - It **SHOULD** preserve the caller's selected Square API version where one is configured. - It **MUST** use Square-native `idempotency_key` fields where duplicate execution protection is required and supported. It **MUST NOT** treat `X-GM-Idempotency-Key` as Square relay deduplication. - It **MUST** distinguish native Square errors from Gateman admission and transport errors and **MUST NOT** blindly retry uncertain mutations. - It **MUST** respect the 4 MiB nested request-body and decoded response-body limits. A larger decoded response returns HTTP 502 `square_response_too_large` without a partial body. - It **MUST** account for one `square.request` operation per admitted invocation, including provider errors, transport failures, and oversized responses. - It **MUST NOT** assume Gateman processes Square webhooks, tracks final payment state, or automatically retries Square requests. - It **MUST NOT** alter Square credentials, merchant/location configuration, or payment workflows without customer authorization. ## Reusable AGENTS.md block ```markdown - Use authenticated Contract v1 with the `square:use` scope and target `POST /square/request`. - Include `environment`: `production` uses the configured Square production credential and origin; `staging` and `development` use the configured Square Sandbox credential and origin and make real Sandbox requests. - Use only `GET`, `POST`, `PUT`, or `DELETE` with a `/v2/` Square path. Gateman uses the fixed Square origin and does not support arbitrary hosts, unsupported methods, or a general multipart/file-upload contract. - Represent the native request body as JSON in the envelope. The nested body is limited to 4 MiB (4,194,304 bytes); Gateman does not convert it to form encoding. - Use only `Square-Version` and `Content-Type` as nested request headers. Gateman supplies Square bearer authorization from the application-scoped credential. - Use Square-native `idempotency_key` fields for provider-side duplicate protection where the selected operation supports them. Do not treat `X-GM-Idempotency-Key` as Square relay deduplication. Gateman does not cache responses or automatically retry Square requests. - Account for one `square.request` operation per admitted invocation, including provider errors, transport failures, and oversized responses. - A decoded Square response body of exactly 4 MiB is accepted. A larger body returns HTTP 502 `square_response_too_large` without partial content; Square may nevertheless have executed the request, so this is not a safe-to-retry signal by itself. - Preserve and interpret Square's native status and body. Gateman forwards `Retry-After` only when Square supplies it and does not synthesize or retry automatically. - Do not assume a successful relay means final payment completion. Square webhook configuration, event receipt and verification, payment reconciliation, and payment-state handling remain customer application responsibilities. - Full capability reference: https://docs.getgateman.com/capabilities/square.use/ ``` ## Related references - [Contract v1](https://docs.getgateman.com/contract-v1/) - [Authentication](https://docs.getgateman.com/authentication/) - [Environments](https://docs.getgateman.com/environments/) - [Idempotency](https://docs.getgateman.com/idempotency/) - [Operation accounting](https://docs.getgateman.com/operation-accounting/) - [Rate limits and concurrency](https://docs.getgateman.com/rate-limits-and-concurrency/) - [Errors and responses](https://docs.getgateman.com/errors-and-responses/) - [Data retention](https://docs.getgateman.com/data-retention/) - [Webhooks and event handling](https://docs.getgateman.com/webhooks-and-event-handling/) - [Official PHP client](https://docs.getgateman.com/canonical-client-php/) - [Official Node.js client](https://docs.getgateman.com/canonical-client-node/) - [Official Python client](https://docs.getgateman.com/canonical-client-python/) - [Official Go client](https://docs.getgateman.com/canonical-client-go/)