Use Square

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 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.

POST /square/request
Content-Type: application/json
X-GM-App: app_example
X-GM-Ts: 1791748800
X-GM-Sig: <Contract-v1-signature>
X-GM-Idempotency-Key: optional-gateman-key

{
  "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

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

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/1.1 502 Bad Gateway
Content-Type: application/json; charset=utf-8

{
  "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 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 and Rate limits and concurrency.

Errors and uncertain outcomes

The exact shared authentication, response-header, and error-envelope rules are defined by Errors and responses and 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 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

<!-- gateman:begin capability=square:use -->
- 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/
<!-- gateman:end capability=square:use -->

Related references

• Contract v1
• Authentication
• Environments
• Idempotency
• Operation accounting
• Rate limits and concurrency
• Errors and responses
• Data retention
• Webhooks and event handling
• Official PHP client
• Official Node.js client
• Official Python client
• Official Go client