sasa-membership/SQUARE_PAYMENT_SETUP.md

Square Payment Integration Setup Guide

This guide walks you through setting up Square payment processing for the SASA Membership Portal.

Overview

The application supports two payment methods:

• Square Payments: Credit/debit card payments processed through Square's Web Payments SDK
• Cash Payments: Manual payments recorded by administrators

Prerequisites

1. A Square Developer account
2. Access to the Square Developer Dashboard
3. Square Sandbox credentials for testing (included with all Square accounts)

Setup Steps

1. Create a Square Developer Account

1. Go to Square Developer Portal
2. Sign up for a free developer account or log in with your existing Square account
3. Navigate to the Applications Dashboard

2. Create or Select an Application

1. In the Applications Dashboard, create a new application or select an existing one
2. Name your application (e.g., "SASA Membership Portal")
3. Click "Save"

3. Get Your Credentials

For Sandbox (Testing):

1. In your application, go to the Sandbox tab
2. Copy the following credentials:
   • Sandbox Access Token: Found under "Sandbox Access Token"
   • Sandbox Application ID: Found under "Sandbox Application ID"
   • Sandbox Location ID: Click on "Locations" to find your sandbox location ID

For Production (Live Payments):

1. In your application, go to the Production tab
2. Copy the following credentials:
   • Production Access Token: Found under "Production Access Token"
   • Production Application ID: Found under "Production Application ID"
   • Production Location ID: Click on "Locations" to find your production location ID

4. Configure Environment Variables

Update your .env file with the Square credentials:

# For Sandbox (Testing)
SQUARE_ACCESS_TOKEN=EAAAl...  # Your Sandbox Access Token
SQUARE_ENVIRONMENT=sandbox
SQUARE_LOCATION_ID=LXXX...    # Your Sandbox Location ID
SQUARE_APPLICATION_ID=sandbox-sq0idb-...  # Your Sandbox Application ID

# For Production (Live Payments)
SQUARE_ACCESS_TOKEN=EAAAl...  # Your Production Access Token
SQUARE_ENVIRONMENT=production
SQUARE_LOCATION_ID=LXXX...    # Your Production Location ID
SQUARE_APPLICATION_ID=sq0idp-...  # Your Production Application ID

5. Restart the Application

After updating the environment variables, run the tested restart helper:

./restart.sh

For a manual restart, run docker compose build, docker compose run --rm frontend npm test, docker compose run --rm backend pytest -q, and then docker compose up -d.

Testing with Sandbox

Square provides test card numbers for sandbox testing:

Test Card Numbers

Card Number	Result
4111 1111 1111 1111	Successful payment
4000 0000 0000 0002	Card declined - Insufficient funds
4000 0000 0000 0010	Card declined - CVV failure
5105 1051 0510 5100	Successful payment (Mastercard)

Test CVV: Any 3-digit number (e.g., 111)
Test Expiration: Any future date (e.g., 12/25)
Test Postal Code: Any valid postal code (e.g., 12345)

Testing the Payment Flow

1. Log in to the membership portal
2. Navigate to membership setup
3. Select a membership tier
4. Choose "Credit/Debit Card" as payment method
5. Use one of the test card numbers above
6. Complete the payment

In sandbox mode, no real money is charged.

Features Implemented

Backend (backend/app/)

• services/square_service.py: Core Square integration service

  • Payment processing
  • Payment retrieval
  • Refund processing
  • Customer creation

• api/v1/payments.py: Payment endpoints

  • GET /api/v1/payments/config/square: Get Square configuration for frontend
  • POST /api/v1/payments/square/process: Process Square payment
  • POST /api/v1/payments/square/refund: Refund a payment (admin only)

• schemas/schemas.py: Payment schemas

  • SquarePaymentRequest: Request schema for processing payments
  • SquarePaymentResponse: Response schema for payment results
  • SquareRefundRequest: Request schema for refunds

Frontend (frontend/src/)

• components/SquarePayment.tsx: Square Web Payments SDK integration

  • Card input form
  • Token generation
  • Payment submission
  • Error handling

• components/MembershipSetup.tsx: Updated membership flow

  • Payment method selection
  • Integration with SquarePayment component
  • Cash payment option

• index.html: Square Web Payments SDK script tag

Payment Flow

1. User selects membership tier → Creates pending membership in database
2. User chooses payment method:
   • Square: Square payment form loads
   • Cash: Simple confirmation dialog
3. Square Payment:
   • User enters card details
   • Card is tokenized by Square SDK (PCI-compliant)
   • Token sent to backend
   • Backend processes payment with Square API
   • Payment record created in database
   • Membership activated
   • Confirmation email sent
4. Cash Payment:
   • Payment record created with "pending" status
   • Membership remains "pending"
   • Admin must manually approve

Security Features

• PCI Compliance: Card data never touches your server (handled by Square SDK)
• Tokenization: Card details are converted to secure tokens
• Idempotency: Prevents duplicate payments
• Environment Separation: Clear sandbox/production separation
• Authorization: Payment endpoints require authentication
• Admin Controls: Refunds require admin privileges

Currency

The system is configured for GBP (British Pounds). To change the currency:

1. Update square_service.py line 56: Change 'currency': 'GBP'
2. Update frontend display symbols in MembershipSetup.tsx and SquarePayment.tsx

Troubleshooting

"Failed to load payment configuration"

• Check that SQUARE_APPLICATION_ID is set in .env
• Verify the backend is running and accessible
• Check browser console for CORS errors

"Payment processing failed"

• Verify SQUARE_ACCESS_TOKEN is valid
• Check SQUARE_LOCATION_ID matches your account
• Ensure SQUARE_ENVIRONMENT matches your token type (sandbox/production)
• Check backend logs for detailed error messages

"Card tokenization failed"

• Ensure Square SDK loaded (check Network tab in browser DevTools)
• Verify SQUARE_APPLICATION_ID matches the environment
• Check that test card numbers are valid for sandbox

Database errors

• Ensure squareup package is installed: pip install squareup==43.2.0.20251016
• Restart backend container after updating requirements.txt

Going Live with Production

Before accepting real payments:

1. Get approved by Square: Complete verification in Square Dashboard
2. Update credentials: Switch to production credentials in .env
3. Change environment: Set SQUARE_ENVIRONMENT=production
4. Update SDK URL: In frontend/index.html, change:

   <!-- Change from sandbox -->
   <script src="https://sandbox.web.squarecdn.com/v1/square.js"></script>
   
   <!-- To production -->
   <script src="https://web.squarecdn.com/v1/square.js"></script>
   

5. Test thoroughly: Test the complete flow with real cards (you can refund these)
6. Monitor: Watch for errors in logs and Square Dashboard

Support

• Square Documentation: https://developer.squareup.com/docs/web-payments/overview
• Square Support: https://squareup.com/help/contact
• API Reference: https://developer.squareup.com/reference/square

Additional Resources

• Square Web Payments SDK Guide
• Square Testing Guide
• Square API Reference
• PCI Compliance Info