Square

Purpose

Work with a Square seller account: list locations and payments, create orders, push a checkout to a physical Square Terminal for in-person payment, charge a payment source directly, cancel a pending Terminal checkout, and refund a payment. Reach for this when the user needs to take or return money through Square.

Tooling

All commands go through bin/square.py. Sandbox is the default (--env sandbox); sandbox never moves real money. Add --env prod for production:

bin/square.py auth                                   # verify the token (sandbox)
bin/square.py locations                              # list seller locations
bin/square.py payments --limit 10                    # list payments
bin/square.py payment-get --payment-id PAY_ID        # one payment
bin/square.py order-create --file order.json         # create an order (moves no money)
bin/square.py checkout-create --device-id DEV_ID \
    --amount-cents 1200 --currency USD \
    --confirm "present $12.00 USD charge on terminal DEV_ID"   # push charge to a Terminal
bin/square.py checkout-get --checkout-id CO_ID       # Terminal checkout status
bin/square.py checkout-cancel --checkout-id CO_ID \
    --confirm "cancel terminal checkout CO_ID"        # cancel a pending checkout
bin/square.py charge --source-id SRC_ID \
    --amount-cents 1200 --currency USD \
    --confirm "charge $12.00 USD to payment source SRC_ID"     # charge a payment source
bin/square.py refund --payment-id PAY_ID \
    --amount-cents 1200 --currency USD \
    --confirm "refund $12.00 USD on payment PAY_ID"   # send money back

Amounts are in the currency's smallest unit (--amount-cents 1200 is $12.00). order-create takes a Square order object in JSON and creates an order record only; no money moves until a payment is attached.

Auth

• Provider id: square (credential is collected as custom.square)
• Collection: OAuth 2.0 bearer via the secure credential flow (credentials.request_api_access) for third-party apps, or a personal access token for a single account; the runtime performs the token exchange/refresh and hands the CLI a fresh Bearer token, same pattern as the slack and x connectors
• Auth scheme: Authorization: Bearer <token> on every request
• Allowed hosts: connect.squareup.com, connect.squareupsandbox.com
• Sandbox is the CLI default and is mandatory for testing: https://connect.squareupsandbox.com. Switch to production only with --env prod on the command and a production credential stored.
• Status check: bin/square.py auth

Operating Rules

1. Sandbox is the default and is mandatory for testing. Never run a first-time flow against --env prod. Confirm the flow works in sandbox, then switch.
2. Terminal checkout and direct charges are HIGH actuations. POST /v2/terminals/checkouts presents a charge on a physical Terminal; a customer tapping or inserting a card captures real funds. POST /v2/payments charges a payment source immediately. Both require --confirm with the exact string the CLI echoes (it names the amount, the currency and the target) on every call, in sandbox and in production. Missing or mismatched confirmation refuses the call.
3. Refunds are MEDIUM and move real money back. POST /v2/refunds requires --confirm with the exact echoed string on every call (this is stricter than the standing first-use-only rule, chosen because a mistaken refund is hard to take back).
4. Cancelling a pending Terminal checkout requires --confirm every time; it has no effect once the payment completed.
5. Square charges processing fees per transaction; check squareup.com pricing for current rates. Every write uses an idempotency key so retries cannot double-charge.
6. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/square.py). Do not print, log, or transmit the token.

Files

• SKILL.md
• bin/square.py

Maturity

Draft: written from Square's public API docs; not yet live-tested end-to-end.