{"id":185,"library":"squareup","title":"Square Python SDK","description":"Official Square payments Python SDK. Current version: 44.0.1 (Mar 2026). VERSIONING QUIRK: squareup uses date-based versions (44.0.1.20260122) — major version tracks Square API version. Releases every ~4-6 weeks. Install is 'squareup', import is 'square'. Square uses idempotency_key for all payment creation — required, not optional. Amount in smallest currency unit (cents for USD). Test environment uses sandbox credentials with 'sandbox-' prefix.","status":"active","version":"44.0.1.20260122","language":"python","source_language":"en","source_url":"https://github.com/square/square-python-sdk","tags":["square","payments","python","payment-gateway","pos"],"install":[{"cmd":"pip install squareup","lang":"bash","label":"Python"}],"dependencies":[{"reason":"Required. Installed automatically.","package":"requests","optional":false}],"imports":[{"note":"idempotency_key is REQUIRED for payments. amount is in smallest currency unit (cents for USD). result.is_success() and result.is_error() are methods, not properties.","wrong":"# Wrong: missing idempotency_key\nclient.payments.create_payment({\n    'source_id': 'nonce',\n    'amount_money': {'amount': 100, 'currency': 'USD'}\n    # no idempotency_key — raises ValidationError\n})\n\n# Wrong: amount in dollars\n'amount_money': {'amount': 1.00, 'currency': 'USD'}  # should be 100 cents","symbol":"Client + Payments API","correct":"import square\nimport uuid\n\nclient = square.Client(\n    access_token='YOUR_ACCESS_TOKEN',\n    environment='sandbox'  # or 'production'\n)\n\n# Create payment — idempotency_key required\nresult = client.payments.create_payment({\n    'source_id': 'cnon:card-nonce-ok',  # from Square Web Payments SDK\n    'idempotency_key': str(uuid.uuid4()),  # unique per request\n    'amount_money': {\n        'amount': 100,      # 100 cents = $1.00 USD\n        'currency': 'USD'\n    }\n})\n\nif result.is_success():\n    print(result.body['payment']['id'])\nelif result.is_error():\n    for error in result.errors:\n        print(error['detail'])"}],"quickstart":{"code":"# pip install squareup\nimport square\nimport uuid\n\nclient = square.Client(\n    access_token='EAAAl...',  # sandbox token from developer.squareup.com\n    environment='sandbox'\n)\n\n# Create payment\nresult = client.payments.create_payment({\n    'source_id': 'cnon:card-nonce-ok',  # test nonce\n    'idempotency_key': str(uuid.uuid4()),\n    'amount_money': {\n        'amount': 100,   # cents\n        'currency': 'USD'\n    },\n    'note': 'Test payment'\n})\n\nif result.is_success():\n    payment = result.body['payment']\n    print(f'Payment {payment[\"id\"]}: {payment[\"status\"]}')\nelif result.is_error():\n    for error in result.errors:\n        print(f'Error {error[\"code\"]}: {error[\"detail\"]}')","lang":"python","description":"Square Python SDK — create payment with test nonce."},"warnings":[{"fix":"pip install squareup; then import square","message":"Install is 'squareup' but import is 'import square'. Common confusion — installing 'square' installs a different package.","severity":"breaking","affected_versions":"all"},{"fix":"'idempotency_key': str(uuid.uuid4())","message":"idempotency_key is required for payments.create_payment(). Omitting it raises a validation error. Must be unique per payment attempt.","severity":"breaking","affected_versions":"all"},{"fix":"amount_in_cents = int(amount_in_dollars * 100)","message":"Amount is in smallest currency unit — cents for USD. 100 = $1.00. Passing 1.00 as float or passing dollars will result in undercharging.","severity":"breaking","affected_versions":"all"},{"fix":"if result.is_success(): — not if result.is_success:","message":"result.is_success() and result.is_error() are METHODS not properties. Calling result.is_success without () always returns truthy.","severity":"gotcha","affected_versions":"all"},{"fix":"Check Square changelog before upgrading: developer.squareup.com/docs/changelog","message":"Version numbering is date-based (44.0.1.20260122). Major version tracks Square API version. Pin carefully — minor releases can add breaking API changes.","severity":"gotcha","affected_versions":"all"},{"fix":"Sandbox test nonce: 'cnon:card-nonce-ok'. Production: collect via Square Web Payments JS SDK.","message":"Sandbox uses test card nonces from Square docs. Production uses nonces from Square Web Payments SDK on frontend. Never pass real card numbers as source_id.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T09:49:00.946Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"fix":"Use the correct import statement: `import square`","cause":"The Python package is installed as `squareup` but the correct import statement for the SDK's functionality is `import square`.","error":"ModuleNotFoundError: No module named 'square'"},{"fix":"First initialize the `Client`, then access the API: `client = square.Client(access_token='YOUR_ACCESS_TOKEN', environment='sandbox')\npayments_api = client.payments`","cause":"API classes like `PaymentsApi` are not directly accessible from the top-level `square` module; they must be accessed through an instance of `square.Client`.","error":"AttributeError: module 'square' has no attribute 'PaymentsApi'"},{"fix":"Include a unique `idempotency_key` in your request body, typically a UUID: `body = {\n    \"source_id\": \"cnon:card-nonce-ok\",\n    \"amount_money\": {\"amount\": 100, \"currency\": \"USD\"},\n    \"idempotency_key\": str(uuid.uuid4())\n}`","cause":"The `create_payment` (or other payment-related) API request is missing the mandatory `idempotency_key` field, which Square requires for all payment creation.","error":"square.exceptions.ApiException: ... (status code: 400, category: INVALID_REQUEST_ERROR, code: MISSING_REQUIRED_PARAMETER, detail: Missing required field: idempotency_key)"},{"fix":"Verify that your `access_token` is correct, active, and corresponds to the specified `environment` (e.g., a sandbox token for the `sandbox` environment).","cause":"The `access_token` provided to `square.Client` is either incorrect, expired, or does not have the necessary permissions for the requested operation.","error":"square.exceptions.ApiException: ... (status code: 401, category: AUTHENTICATION_ERROR, code: UNAUTHORIZED, detail: The `Authorization` header is invalid or missing.)"},{"fix":"Always check for the success of the API call and existence of keys before accessing them: `if response.is_success():\n    payment = response.result.get('payment')\n    if payment:\n        # Process payment\nelse:\n    errors = response.errors\n    # Handle errors`","cause":"This typically occurs when trying to access a key like 'payment' directly from an API response dictionary, but the key is missing because the request failed or the response structure is unexpected.","error":"KeyError: 'payment'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"60.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.5,"disk_size":"60M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.6,"disk_size":"64.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"64M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"55.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"56M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.7,"disk_size":"55.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"55M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"59.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"59M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}