Skip to content
Truto
Back
AI & Agents

Connect Square to ChatGPT: Manage Orders, Payments, and Loyalty

Learn how to connect Square to chatgpt using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Uday Gajavalli Uday Gajavalli · · 10 min read
Connect Square to ChatGPT: Manage Orders, Payments, and Loyalty

If you need to connect Square to ChatGPT to automate payment processing, order management, or loyalty program operations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and Square's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses Claude, check out our guide on connecting Square to Claude or explore our broader architectural overview on connecting Square to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling financial ecosystem like Square is an engineering challenge. You have to handle OAuth token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Square's specific optimistic concurrency and idempotency quirks. Every time Square updates an endpoint or deprecates a field, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Square, connect it natively to ChatGPT, and execute complex workflows using natural language.

The Engineering Reality of the Square API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Square's APIs is painful. If you decide to build a custom MCP server for Square, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Square.

Strict Idempotency Requirements

When an LLM executes a tool call to charge a customer or create an order, network timeouts can happen. If the LLM assumes the request failed and retries it, you risk double-charging the customer. Square prevents this by mandating an idempotency_key (a unique string valid for 45 days) for almost all POST and PUT operations. Your MCP server must explicitly instruct the LLM to generate and reuse idempotency keys correctly, or you have to build middleware to inject and cache them. If you fail to handle this, your AI agent will create duplicate transactions.

Optimistic Concurrency and the Version Integer

Updating records in Square is not as simple as sending a PATCH request with the new data. Square uses optimistic concurrency to prevent lost updates. When modifying an Order, Catalog Item, or Customer Profile, the API requires you to pass the current version integer. If an LLM fetches an order, a cashier manually adds a line item on a terminal in the store, and the LLM then attempts to apply a discount using the outdated version number, Square will reject the request with a 409 Conflict. Your agent must be programmed to handle this error, refetch the object to get the latest version, and re-apply the mutation.

Complex Nested Taxonomies

Square's data models are highly relational. Creating an order is not a flat JSON payload. An order requires a location_id. Line items require a catalog_object_id. Taxes and discounts are applied via arrays of highly specific nested objects. If your MCP server does not meticulously map these nested requirements into clear JSON Schema descriptions, the LLM will hallucinate catalog IDs or structure the line items incorrectly, resulting in standard 400 Bad Request validation errors.

Rate Limits and the 429 Reality

Square enforces rate limits on API requests. When an AI agent gets stuck in a loop or attempts to retrieve thousands of historical payments for analysis without proper pagination logic, Square will return a 429 Too Many Requests error. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When Square returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller - in this case, your AI agent's executing framework - is entirely responsible for observing these headers and implementing its own retry or exponential backoff logic.

How to Generate a Managed Square MCP Server

Instead of forcing your engineering team to build a custom JSON-RPC layer and maintain Square schemas, you can use Truto to generate an MCP server dynamically. Truto translates Square's API documentation and endpoint definitions into an MCP-compliant JSON-RPC endpoint.

Every MCP server in Truto is scoped to a single integrated account. The server URL contains a cryptographic token that authenticates the client, routes the request to the correct Square tenant, and scopes the available tools based on your configuration.

Here is how to create a Square MCP server.

Method 1: Via the Truto UI

For IT administrators and operations teams, the Truto dashboard provides a visual interface for generating MCP servers.

  1. Navigate to the Integrated Accounts page in your Truto environment.
  2. Select your connected Square instance.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration. You can optionally filter tools by method (e.g., read, write) or by tags (e.g., orders, payments).
  6. Click Generate and copy the resulting MCP server URL.

Method 2: Via the Truto API

For engineering teams building multi-tenant AI agents, you can generate MCP servers programmatically for your users. Call the /integrated-account/:id/mcp endpoint to provision a secure token.

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Square Payments and Loyalty Agent",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["payments", "orders", "loyalty"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the token, stores the hash in Cloudflare KV for sub-millisecond validation, and returns the endpoint you need to provide to your LLM.

{
  "id": "mcp_abc123",
  "name": "Square Payments and Loyalty Agent",
  "url": "https://api.truto.one/mcp/TOKEN_STRING_HERE"
}

Connecting the Square MCP Server to ChatGPT

Once you have your Truto MCP URL, you need to register it with your AI client. The URL is entirely self-contained - it handles the OAuth flow, pagination cursors, and schema generation automatically.

Method A: Via the ChatGPT UI

If you are using ChatGPT Plus, Team, or Enterprise, you can connect the server natively through the interface.

  1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
  2. Toggle Developer mode to the "On" position.
  3. Under the custom connectors section, select Add a new server.
  4. Give the connector a name (e.g., "Square Production").
  5. Paste the Truto MCP server URL into the endpoint field.
  6. Click Add.

ChatGPT will immediately issue an initialize JSON-RPC handshake to Truto, fetch the Square tools, and store them in its context window.

Method B: Via Manual Config File

If you are connecting an open-source MCP client, an agent framework, or a desktop client like Claude Desktop, you can configure the connection manually using the Server-Sent Events (SSE) transport adapter.

Create or update your mcp_config.json file:

{
  "mcpServers": {
    "square_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/TOKEN_STRING_HERE"
      ]
    }
  }
}

Restart your client. The framework will bind to the proxy, enabling standard natural language tool execution.

Hero Tools for Square Automation

Truto automatically generates over 100 tools for Square based on their API definitions. When your LLM issues a tools/call command, Truto splits the single flat argument object into the precise query parameters and body payloads Square expects. Here are the highest-leverage tools for automating operations.

create_a_square_order

This tool allows the agent to construct an order programmatically. Because orders are highly nested, the agent will prompt for or infer line item details, quantities, and the required location_id.

"A customer just emailed to buy 3 bags of the 'Sumatra Dark Roast' coffee. Look up our primary location ID, construct a new draft order for these items, and return the order ID to me."

create_a_square_payment

This tool handles capturing funds. It requires an idempotency_key, the amount_money object (which specifies the exact integer amount in the lowest denomination, like cents, and the currency), and a source_id (a card nonce or a saved card on file).

"Take the order ID we just created, generate a unique idempotency key, and charge $45.00 to the customer's saved card on file (source ID: ccof_1234). Provide the payment confirmation ID."

create_a_square_refund

This tool issues refunds for completed payments. It is incredibly useful for customer support agents dealing with disputed charges or returned merchandise.

"The customer with payment ID 'pay_9876' requested a refund because their item arrived damaged. Issue a full refund for the transaction amount, use the reason 'Damaged in transit', and confirm when the refund status is processing."

square_loyalty_accounts_adjust_points

Managing loyalty accounts manually takes time. This tool allows the AI to add or subtract points from a specific loyalty account ID, bypassing the need for a cashier to execute the change on a physical terminal.

"Find the loyalty account linked to phone number 555-0199. Manually add 150 points to their balance as an apology for their late delivery. Set the adjustment reason to 'Customer Service Resolution'."

list_all_square_shifts

Beyond commerce, Square manages labor. This tool allows an agent to query labor shifts, filter them by employee or location, and assess timecard data.

"List all labor shifts at the Downtown location for the past 7 days. Identify any employee who worked more than 40 hours and calculate their total overtime duration."

To view the complete schema details, JSON payloads, and the full inventory of available tools, review the Truto Square integration page.

Workflows in Action

Exposing tools individually is helpful, but the true power of an MCP server emerges when an LLM orchestrates multi-step workflows. Because the model maintains context between requests, it can feed the output of one API call directly into the input of the next.

Scenario 1: Support Automation (Refund and Loyalty Compensation)

Customer service representatives often juggle multiple screens to handle a simple complaint. An AI agent can perform the entire operational sequence based on natural language intent.

"A customer named Sarah Jenkins complained that her order from yesterday was missing an item. Find her payment, refund $12.00 to her card, and add 50 bonus points to her loyalty account to make up for the mistake."

  1. list_all_square_payments: The agent searches recent payments to locate the transaction associated with Sarah Jenkins.
  2. create_a_square_refund: Using the retrieved payment_id, the agent executes a partial refund of 1200 cents ($12.00) against the original payment source.
  3. list_all_square_loyalty_accounts: The agent queries the loyalty API using Sarah's associated customer profile or phone number.
  4. square_loyalty_accounts_adjust_points: The agent injects 50 points into the retrieved loyalty account ID, recording the action with the reason "Customer service compensation".
sequenceDiagram
    participant User
    participant ChatGPT
    participant Truto MCP
    participant Square API

    User->>ChatGPT: "Refund $12 to Sarah and give 50 loyalty points"
    ChatGPT->>Truto MCP: Call list_all_square_payments
    Truto MCP->>Square API: GET /v2/payments
    Square API-->>ChatGPT: Return payment_id: pay_123
    ChatGPT->>Truto MCP: Call create_a_square_refund(pay_123, 1200)
    Truto MCP->>Square API: POST /v2/refunds
    Square API-->>ChatGPT: Refund Processing
    ChatGPT->>Truto MCP: Call list_all_square_loyalty_accounts
    Truto MCP->>Square API: POST /v2/loyalty/accounts/search
    Square API-->>ChatGPT: Return loyalty_account_id: loy_456
    ChatGPT->>Truto MCP: Call square_loyalty_accounts_adjust_points(loy_456, 50)
    Truto MCP->>Square API: POST /v2/loyalty/accounts/loy_456/adjust
    Square API-->>ChatGPT: Balance Updated
    ChatGPT-->>User: "Refund issued and 50 points added."

Scenario 2: E-Commerce Chatbot Checkout

If you embed ChatGPT into a storefront interface, it can handle the entire cart construction and payment authorization process conversationally.

"I want to buy a medium t-shirt and ship it to my saved address. Use the card I have on file to pay for it."

  1. list_all_square_catalog_objects: The agent searches the catalog to find the exact item variation ID for the "medium t-shirt".
  2. create_a_square_order: The agent builds the nested JSON payload, mapping the retrieved catalog object ID into a new order line item, and creates the order.
  3. list_all_square_cards: The agent queries the customer's profile to locate their ccof (card on file) source ID.
  4. create_a_square_payment: The agent generates a random idempotency_key and charges the order total against the retrieved card source ID, successfully completing the transaction.

Security and Access Control

Giving an AI write access to a financial system requires strict governance. Truto MCP servers enforce authorization at the infrastructure layer, ensuring the LLM can only execute the tools you explicitly permit.

  • Method Filtering: You can restrict an MCP server to read-only operations by passing methods: ["read"] during server creation. This allows the AI to analyze payments and orders without the ability to create charges or issue refunds.
  • Tag Filtering: You can scope the server's domain by applying tags. Setting tags: ["loyalty", "shifts"] ensures the LLM can only interact with employee schedules and reward points, isolating it entirely from raw payment processing endpoints.
  • Require API Token Auth: By default, possessing the MCP URL is enough to connect. Setting require_api_token_auth: true mandates that the connecting client also passes a valid Truto session or API token in the headers, preventing unauthorized access if the URL is leaked.
  • Time-to-Live (TTL): Providing the expires_at ISO datetime automatically shreds the MCP server token and its Cloudflare KV entries at the specified time. This is ideal for granting an external auditor or temporary contractor temporary AI access to your Square data.

Closing the Execution Gap

Connecting Square to ChatGPT transforms your AI from a conversational interface into an autonomous financial and operational agent. Instead of requiring cashiers, store managers, and back-office staff to execute manual API requests or navigate dense dashboards, natural language becomes the control plane for your entire physical and digital business.

By utilizing Truto's dynamically generated MCP servers, your engineering team skips the boilerplate. You avoid the pain of mapping nested JSON schemas, building custom OAuth credential refreshes, and managing complex idempotency logic. You get secure, deterministic execution from day one.

More from our Blog