Square | Composio Docs

Overview

SLUG: SQUARE

Description

Square provides payment processing, POS systems, invoicing, and e-commerce tools, enabling sellers to accept card payments and manage their business

Authentication Details

OAuth2

client_id

stringRequired

client_secret

stringRequired

full

stringDefaults to https://connect.squareup.comRequired

oauth_redirect_uri

stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add

scopes

stringDefaults to CUSTOMERS_READ,CUSTOMERS_WRITE,MERCHANT_PROFILE_READ,MERCHANT_PROFILE_WRITE

bearer_token

string

API Key

full

stringDefaults to https://connect.squareup.comRequired

generic_api_key

stringRequired

Connecting to Square

Create an auth config

Use the dashboard to create an auth config for the Square toolkit. This allows you to connect multiple Square accounts to Composio for agents to use.

Select App

Navigate to Square.

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

Create and Get auth config ID

Click “Create Square Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1 from composio import Composio
2 
3 # Replace these with your actual values
4 square_auth_config_id = "ac_YOUR_SQUARE_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/application
6 
7 composio = Composio()
8 
9 
10 def authenticate_toolkit(user_id: str, auth_config_id: str):
11     connection_request = composio.connected_accounts.initiate(
12         user_id=user_id,
13         auth_config_id=auth_config_id,
14     )
15 
16     print(
17         f"Visit this URL to authenticate Square: {connection_request.redirect_url}"
18     )
19 
20     # This will wait for the auth flow to be completed
21     connection_request.wait_for_connection(timeout=15)
22     return connection_request.id
23 
24 
25 connection_id = authenticate_toolkit(user_id, square_auth_config_id)
26 
27 # You can also verify the connection status using:
28 connected_account = composio.connected_accounts.get(connection_id)
29 print(f"Connected account: {connected_account}")

Using API Key

1 from composio import Composio
2 
3 # Replace these with your actual values
4 square_auth_config_id = "ac_YOUR_SQUARE_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/app
6 
7 composio = Composio()
8 
9 def authenticate_toolkit(user_id: str, auth_config_id: str):
10     # Replace this with a method to retrieve an API key from the user.
11     # Or supply your own.
12     user_api_key = input("[!] Enter API key")
13 
14     connection_request = composio.connected_accounts.initiate(
15         user_id=user_id,
16         auth_config_id=auth_config_id,
17         config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18     )
19 
20     # API Key authentication is immediate - no redirect needed
21     print(f"Successfully connected Square for user {user_id}")
22     print(f"Connection status: {connection_request.status}")
23     
24     return connection_request.id
25 
26 
27 connection_id = authenticate_toolkit(user_id, square_auth_config_id)
28 
29 # You can verify the connection using:
30 connected_account = composio.connected_accounts.get(connection_id)
31 print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Square toolkit’s playground

OpenAI (Python)

Anthropic (TypeScript)

Google (Python)

Vercel (TypeScript)

Python

1 from composio import Composio
2 from openai import OpenAI
3 import json
4 
5 openai = OpenAI()
6 composio = Composio()
7 
8 # User ID must be a valid UUID format
9 user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10 
11 tools = composio.tools.get(user_id=user_id, toolkits=["SQUARE"])
12 
13 print("[!] Tools:")
14 print(json.dumps(tools))
15 
16 def invoke_llm(task = "What can you do?"):
17     completion = openai.chat.completions.create(
18         model="gpt-4o",
19         messages=[
20             {
21                 "role": "user",
22                 "content": task,  # Your task here!
23             },
24         ],
25         tools=tools,
26     )
27 
28     # Handle Result from tool call
29     result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30     print(f"[!] Completion: {completion}")
31     print(f"[!] Tool call result: {result}")
32 
33 invoke_llm()

Tool List

SQUARE_ACCEPT_DISPUTE

Tool Name: Accept Dispute

Description

Tool to accept a dispute and mark it as lost. Use after reviewing all evidence and deciding to accept liability.

Action Parameters

dispute_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_CANCEL_INVOICE

Tool Name: Cancel Invoice

Description

Tool to cancel an invoice. Use when you need to void an existing invoice; ensure the invoice isn't in DRAFT or a terminal state before cancelling.

Action Parameters

invoice_id

stringRequired

version

integerRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_CANCEL_PAYMENT

Tool Name: Cancel Payment

Description

Tool to cancel a payment. Use after confirming the payment is in APPROVED status.

Action Parameters

payment_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_CREATE_CARD

Tool Name: Create Card

Description

Tool to create a card on file. Use when you need to securely store a customer's card for future payments. Requires a valid nonce or payment ID.

Action Parameters

card

objectRequired

idempotency_key

stringRequired

source_id

stringRequired

verification_token

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_CREATE_DISPUTE_EVIDENCE_FILE

Tool Name: Create Dispute Evidence File

Description

Tool to upload a file as dispute evidence. Use when you need to attach supporting documents (PDF, image, etc.) to an existing dispute. Use after creating or retrieving a dispute.

Action Parameters

content_type

string

dispute_id

stringRequired

evidence_type

string

file

objectRequired

idempotency_key

stringRequired

inline_file_content_base64

string

inline_file_mimetype

string

inline_file_name

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_CREATE_DISPUTE_EVIDENCE_TEXT

Tool Name: Create Dispute Evidence Text

Description

Tool to upload text as evidence for a dispute challenge. Endpoint: POST /v2/disputes/{dispute_id}/evidence-text

Action Parameters

dispute_id

stringRequired

evidence_text

stringRequired

evidence_type

string

idempotency_key

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_CREATE_INVOICE_ATTACHMENT

Tool Name: Create Invoice Attachment

Description

Tool to upload a file and attach it to a Square invoice. Use when you need to add supplementary documents to an invoice in DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state.

Action Parameters

description

string

file

objectRequired

idempotency_key

string

inline_file_content_base64

string

inline_file_mimetype

string

inline_file_name

string

invoice_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_DELETE_DISPUTE_EVIDENCE

Tool Name: Delete Dispute Evidence

Description

Tool to delete specified evidence from a dispute. Use when you need to remove an evidence item that is no longer relevant. Use after verifying dispute_id and evidence_id.

Action Parameters

dispute_id

stringRequired

evidence_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_DELETE_INVOICE

Tool Name: Delete Invoice

Description

Tool to delete a Square invoice (only DRAFT invoices can be deleted).

Action Parameters

invoice_id

stringRequired

version

integer

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_DELETE_INVOICE_ATTACHMENT

Tool Name: Delete Invoice Attachment

Description

Tool to delete an attachment from a Square invoice. Endpoint: DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id}

Action Parameters

attachment_id

stringRequired

invoice_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_DELETE_WEBHOOK_SUBSCRIPTION

Tool Name: Delete Webhook Subscription

Description

Tool to delete a Square webhook subscription by ID.

Action Parameters

subscription_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_GET_DISPUTE_EVIDENCE

Tool Name: Get Dispute Evidence

Description

Tool to retrieve a specific evidence item associated with a given dispute. Endpoint: GET /v2/disputes/{dispute_id}/evidence/{evidence_id}

Action Parameters

dispute_id

stringRequired

evidence_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_GET_INVOICE

Tool Name: Get Invoice

Description

Tool to retrieve an invoice by ID. Use when you already have an invoice ID and need its details.

Action Parameters

invoice_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_LIST_DISPUTE_EVIDENCE

Tool Name: List Dispute Evidence

Description

Tool to list evidence items associated with a given dispute. Endpoint: GET /v2/disputes/{dispute_id}/evidence

Action Parameters

cursor

string

dispute_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_LIST_INVOICES

Tool Name: List Invoices

Description

Tool to list invoices for a Square location.

Action Parameters

cursor

string

limit

integer

location_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_LIST_WEBHOOK_EVENT_TYPES

Tool Name: List Webhook Event Types

Description

Tool to list available webhook event types. Use when you need to discover event types before creating or updating a webhook subscription.

Action Parameters

api_version

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_LIST_WEBHOOK_SUBSCRIPTIONS

Tool Name: List Webhook Subscriptions

Description

Tool to list webhook subscriptions. Use when you need to retrieve a page of webhook subscriptions for your application; supports pagination.

Action Parameters

cursor

string

include_disabled

boolean

limit

integer

sort_order

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_RETRIEVE_DISPUTE

Tool Name: Retrieve Dispute

Description

Tool to retrieve a Square dispute by ID. Endpoint: GET /v2/disputes/{dispute_id}

Action Parameters

dispute_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_RETRIEVE_ORDER

Tool Name: Retrieve Order

Description

Tool to retrieve an order by its ID. Use when you have an order ID and need to fetch its details.

Action Parameters

order_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_RETRIEVE_PAYMENT_LINK

Tool Name: Retrieve Payment Link

Description

Tool to retrieve a payment link by ID. Use when you need to fetch full details of a specific checkout link.

Action Parameters

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_RETRIEVE_WEBHOOK_SUBSCRIPTION

Tool Name: Retrieve Webhook Subscription

Description

Tool to retrieve a Square webhook subscription by ID.

Action Parameters

subscription_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_SUBMIT_DISPUTE_EVIDENCE

Tool Name: Submit Dispute Evidence

Description

Tool to submit evidence for a dispute. Use when you have compiled all supporting documentation and want to send it to the cardholder's bank before the due date.

Action Parameters

dispute_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_TEST_WEBHOOK_SUBSCRIPTION

Tool Name: Test Webhook Subscription

Description

Tool to test a webhook subscription. Use after creating or updating a subscription to verify its endpoint.

Action Parameters

event_type

string

subscription_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_UPDATE_ORDER

Tool Name: Update Order

Description

Tool to update an order. Use when modifying fields on an existing open order; requires the latest version for optimistic concurrency.

Action Parameters

fields_to_clear

array

idempotency_key

string

order

object

order_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_UPDATE_WEBHOOK_SUBSCRIPTION

Tool Name: Update Webhook Subscription

Description

Tool to update a Square webhook subscription. Use when you need to modify subscription settings such as name, enabled state, event types, notification URL, or API version of an existing webhook subscription.

Action Parameters

api_version

string

enabled

boolean

event_types

array

name

string

notification_url

string

subscription_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

SQUARE_UPDATE_WEBHOOK_SUBSCRIPTION_SIGNATURE_KEY

Tool Name: Update Webhook Subscription Signature Key

Description

Tool to rotate the signature key for a webhook subscription. Use when you need to replace the current signature key for security purposes.

Action Parameters

idempotency_key

string

subscription_id

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired