Appearance
Square Connection
The Square Connection authorizes supported Square payment and account operations. It can be used by supported Payment Widgets, Cloud Flow server methods, the $io.square API, authenticated SDK access, and supported AI Agent capabilities.
Square's payment commands are used by supported payment interfaces but are not exposed as general-purpose commands in the Page Flow or Cloud Flow command selector.
Capabilities
| Capability | Availability |
|---|---|
| Connection service identifier | square |
| Payment Widget support | Supported |
| Page Flow command selection | Not exposed as a general command interface |
| Cloud Flow direct command selection | Not exposed as a general command interface |
| Connection methods | Supported |
| Server API | $io.square |
| Authenticated SDK object | Supported through service name square |
| AI Agent Connection support | Supported |
| MCP tool support | Supported where offered by the AI Agent workflow |
Profile Settings
| Setting | Purpose |
|---|---|
| Environment | Select sandbox or production. |
| Profile Mode | Select direct access token, ioLoop OAuth2, or custom OAuth2. |
| Currency Code | Three-letter currency code such as USD, CAD, or EUR. |
| Access Token | Direct provider token for Custom Access Token mode. |
| Application ID | Square Application ID used by the selected custom mode. |
| Custom OAuth2 Application Secret | Secret for a custom Square OAuth application. |
| Custom OAuth2 Access Scope | Optional space-separated scopes for custom OAuth. |
The required fields depend on the selected Profile mode. Keep sandbox and production Profiles separate so a Connection cannot silently change environments through credential replacement.
Connection Settings
| Setting | Purpose |
|---|---|
| Square Location ID | Optional Square location under which supported operations run. |
Use a location that belongs to the authenticated Square merchant. When a Project operates across locations, create clearly named Connections so workflows select the intended location.
Server Methods and SDK
The $io.square API includes supported operations such as listing payments, direct API calls, and invoking supported SDK operations.
The Connection Function Call block can invoke documented Square methods. Custom Cloud Flow code can use $io.square directly or obtain the authenticated SDK object with $io.system.sdkLibraryObjectFromConnection('square', connectionName).
Prefer named Server API methods when they cover the operation. Use the SDK object for additional supported Square functionality.
Payment Workflows
Use the supported Payment Widget when building a Square checkout experience. Treat browser-provided amounts, order data, and payment tokens as input to trusted server-side validation.
Before creating or completing a payment, Cloud Flow should verify the relevant order, amount, currency, and fulfillment rules. A browser response alone should not authorize delivery of goods or services.
Testing
Start with a sandbox Profile and controlled Square test data. Verify:
- The Connection uses the intended environment and merchant.
- The location belongs to that merchant.
- Currency and amount handling are correct.
- Successful, declined, duplicate, and interrupted payments are handled.
- Production credentials are configured only after the sandbox workflow is complete.
Sandbox and production data are separate at the provider. Do not expect a sandbox identifier to work with a production Profile.