square-terminal
Use when working with Square Terminal API for in-person payments, device pairing, terminal checkout flows, or POS application integration. Also use when setting up Square Terminal hardware or debugging device connectivity.
| Model | Source |
|---|---|
| sonnet | pack: payments |
Full Reference
┏━ 🔧 square-terminal ━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Use when working with Square Terminal API for … ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Square Terminal API
Section titled “Square Terminal API”Connects POS applications to Square Terminal hardware for in-person payments via Square’s servers. No direct POS-to-hardware connection.
| API Version | Base URL | Node SDK | Python SDK |
|---|---|---|---|
| 2026-01-22 | https://connect.squareup.com/v2 | npm install square (v40+) | pip install squareup (v42+) |
Reference
Section titled “Reference”| Topic | File |
|---|---|
| SDK setup, auth, OAuth permissions, architecture | reference/authentication.md |
| Device pairing, device codes, hardware support | reference/device-pairing.md |
| Terminal checkout — create, cancel, search, tips | reference/terminal-checkout.md |
| Terminal Actions (PING, SAVE_CARD, etc.) | reference/terminal-actions.md |
| Webhook handler, events, signature verification | reference/webhooks.md |
Card surcharge (app_fee_money) | reference/card-surcharge.md |
| Error codes, connectivity troubleshooting | reference/error-handling.md |
| Sandbox setup, simulator, retired APIs | reference/testing.md |
Usage: Read the reference file matching your current task from the index above. Each file is self-contained with code examples and inline gotchas.
Common Mistakes
Section titled “Common Mistakes”| Mistake | Fix |
|---|---|
| Using Dashboard device code instead of API device code | Only use device_id from CreateDeviceCode response |
| Trusting checkout amount as final | Always verify against the Payment object — tips change the total |
| Trying to cancel a COMPLETED checkout | Only PENDING and IN_PROGRESS can be canceled |
| Cash payments via Terminal API | Terminal API doesn’t support cash — use Payments API |
Using legacy SquareConnect package | Use square package v40+ with SquareClient |
| Device code not used within 5 minutes | Code expires — create a new one |
| Skipping webhook signature verification | Always verify X-Square-Hmacsha256-Signature |
| Not reading Payment object after COMPLETED | Checkout amount excludes tip; Payment object has the real total |