Square Python SDK

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

• pip install squareup Python

Imports

• Client + Payments API

  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

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"]}')