Square Python SDK

44.0.1.20260122 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install squareup

Common errors

error ModuleNotFoundError: No module named 'square' ↓

cause The Python package is installed as `squareup` but the correct import statement for the SDK's functionality is `import square`.

fix

Use the correct import statement: import square

error AttributeError: module 'square' has no attribute 'PaymentsApi' ↓

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`.

fix

First initialize the Client, then access the API:

client = square.Client(access_token='YOUR_ACCESS_TOKEN', environment='sandbox')
payments_api = client.payments

error square.exceptions.ApiException: ... (status code: 400, category: INVALID_REQUEST_ERROR, code: MISSING_REQUIRED_PARAMETER, detail: Missing required field: idempotency_key) ↓

cause The `create_payment` (or other payment-related) API request is missing the mandatory `idempotency_key` field, which Square requires for all payment creation.

fix

Include a unique idempotency_key in your request body, typically a UUID:

body = {
    "source_id": "cnon:card-nonce-ok",
    "amount_money": {"amount": 100, "currency": "USD"},
    "idempotency_key": str(uuid.uuid4())
}

error square.exceptions.ApiException: ... (status code: 401, category: AUTHENTICATION_ERROR, code: UNAUTHORIZED, detail: The `Authorization` header is invalid or missing.) ↓

cause The `access_token` provided to `square.Client` is either incorrect, expired, or does not have the necessary permissions for the requested operation.

fix

Verify that your access_token is correct, active, and corresponds to the specified environment (e.g., a sandbox token for the sandbox environment).

error KeyError: 'payment' ↓

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.

fix

Always check for the success of the API call and existence of keys before accessing them:

if response.is_success():
    payment = response.result.get('payment')
    if payment:
        # Process payment
else:
    errors = response.errors
    # Handle errors

Warnings

breaking Install is 'squareup' but import is 'import square'. Common confusion — installing 'square' installs a different package. ↓

fix pip install squareup; then import square

breaking idempotency_key is required for payments.create_payment(). Omitting it raises a validation error. Must be unique per payment attempt. ↓

fix 'idempotency_key': str(uuid.uuid4())

breaking Amount is in smallest currency unit — cents for USD. 100 = $1.00. Passing 1.00 as float or passing dollars will result in undercharging. ↓

fix amount_in_cents = int(amount_in_dollars * 100)

gotcha result.is_success() and result.is_error() are METHODS not properties. Calling result.is_success without () always returns truthy. ↓

fix if result.is_success(): — not if result.is_success:

gotcha Version numbering is date-based (44.0.1.20260122). Major version tracks Square API version. Pin carefully — minor releases can add breaking API changes. ↓

fix Check Square changelog before upgrading: developer.squareup.com/docs/changelog

gotcha 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. ↓

fix Sandbox test nonce: 'cnon:card-nonce-ok'. Production: collect via Square Web Payments JS SDK.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 60.4M

3.10 slim (glibc) - - 0.00s 60M

3.11 alpine (musl) - - 0.02s 64.4M

3.11 slim (glibc) - - 0.01s 64M

3.12 alpine (musl) - - 0.01s 55.8M

3.12 slim (glibc) - - 0.01s 56M

3.13 alpine (musl) - - 0.01s 55.1M

3.13 slim (glibc) - - 0.01s 55M

3.9 alpine (musl) - - 0.01s 59.7M

3.9 slim (glibc) - - 0.01s 59M

Imports

Client + Payments API

wrong

# Wrong: missing idempotency_key
client.payments.create_payment({
    'source_id': 'nonce',
    'amount_money': {'amount': 100, 'currency': 'USD'}
    # no idempotency_key — raises ValidationError
})

# Wrong: amount in dollars
'amount_money': {'amount': 1.00, 'currency': 'USD'}  # should be 100 cents

correct

import square
import uuid

client = square.Client(
    access_token='YOUR_ACCESS_TOKEN',
    environment='sandbox'  # or 'production'
)

# Create payment — idempotency_key required
result = client.payments.create_payment({
    'source_id': 'cnon:card-nonce-ok',  # from Square Web Payments SDK
    'idempotency_key': str(uuid.uuid4()),  # unique per request
    'amount_money': {
        'amount': 100,      # 100 cents = $1.00 USD
        'currency': 'USD'
    }
})

if result.is_success():
    print(result.body['payment']['id'])
elif result.is_error():
    for error in result.errors:
        print(error['detail'])

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.

Quickstart stale last tested: 2026-04-23

Square Python SDK — create payment with test nonce.

# pip install squareup
import square
import uuid

client = square.Client(
    access_token='EAAAl...',  # sandbox token from developer.squareup.com
    environment='sandbox'
)

# Create payment
result = client.payments.create_payment({
    'source_id': 'cnon:card-nonce-ok',  # test nonce
    'idempotency_key': str(uuid.uuid4()),
    'amount_money': {
        'amount': 100,   # cents
        'currency': 'USD'
    },
    'note': 'Test payment'
})

if result.is_success():
    payment = result.body['payment']
    print(f'Payment {payment["id"]}: {payment["status"]}')
elif result.is_error():
    for error in result.errors:
        print(f'Error {error["code"]}: {error["detail"]}')