# 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](https://developer.squareup.com/)
2. Sign up for a free developer account or log in with your existing Square account
3. Navigate to the [Applications Dashboard](https://developer.squareup.com/apps)

### 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:

```bash
# 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, restart your Docker containers:

```bash
docker-compose down
docker-compose up -d --build
```

## 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:
   ```html
   <!-- 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](https://developer.squareup.com/docs/web-payments/overview)
- [Square Testing Guide](https://developer.squareup.com/docs/testing/test-values)
- [Square API Reference](https://developer.squareup.com/reference/square)
- [PCI Compliance Info](https://developer.squareup.com/docs/security)