Square Payments

2025-11-12 16:09:38 +00:00
parent be2426c078
commit 0f74333a22
19 changed files with 1828 additions and 85 deletions
--- a/SQUARE_PAYMENT_SETUP.md
+++ b/SQUARE_PAYMENT_SETUP.md
@@ -0,0 +1,229 @@
+# 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)