# Square Payment Integration - Implementation Checklist

## ✅ Completed Tasks

### Backend Implementation
- [x] Added Square SDK to `requirements.txt` (squareup==43.2.0.20251016)
- [x] Created `square_service.py` with payment processing logic
- [x] Added Square configuration to `config.py` (SQUARE_APPLICATION_ID)
- [x] Created Square payment schemas in `schemas.py`
  - [x] SquarePaymentRequest
  - [x] SquarePaymentResponse
  - [x] SquareRefundRequest
- [x] Added Square payment endpoints to `payments.py`
  - [x] GET /api/v1/payments/config/square
  - [x] POST /api/v1/payments/square/process
  - [x] POST /api/v1/payments/square/refund

### Frontend Implementation
- [x] Created `SquarePayment.tsx` component
  - [x] Square Web Payments SDK integration
  - [x] Card input form
  - [x] Payment tokenization
  - [x] Error handling
- [x] Updated `MembershipSetup.tsx` component
  - [x] Payment method selection UI
  - [x] Integration with SquarePayment
  - [x] Cash payment option
  - [x] Improved flow logic
- [x] Added Square SDK script to `index.html`

### Configuration
- [x] Updated `.env.example` with Square variables and comments
- [x] Verified all Square config variables in `config.py`

### Documentation
- [x] Created `SQUARE_PAYMENT_SETUP.md` - Comprehensive setup guide
- [x] Created `SQUARE_IMPLEMENTATION.md` - Implementation details
- [x] Created `SQUARE_QUICKSTART.md` - Quick start guide
- [x] Created `deploy-square.sh` - Deployment helper script

### Code Quality
- [x] No Python syntax errors
- [x] Proper error handling implemented
- [x] Security best practices followed
- [x] PCI compliance maintained (tokenization)

## 📋 Deployment Checklist

Before deploying, complete these steps:

### 1. Square Account Setup
- [ ] Create/login to Square Developer account
- [ ] Create application in Square Dashboard
- [ ] Copy Sandbox credentials:
  - [ ] Access Token
  - [ ] Application ID
  - [ ] Location ID

### 2. Environment Configuration
- [ ] Create/update `.env` file
- [ ] Add SQUARE_ACCESS_TOKEN
- [ ] Add SQUARE_APPLICATION_ID
- [ ] Add SQUARE_LOCATION_ID
- [ ] Set SQUARE_ENVIRONMENT=sandbox

### 3. Deployment
- [ ] Run `./deploy-square.sh` OR
- [ ] Run `docker-compose down`
- [ ] Run `docker-compose up -d --build`
- [ ] Verify containers are running: `docker-compose ps`

### 4. Testing
- [ ] Access frontend at http://localhost:3000
- [ ] Login/register a user
- [ ] Navigate to membership setup
- [ ] Select a membership tier
- [ ] Choose "Credit/Debit Card" payment
- [ ] Test with card: 4111 1111 1111 1111
- [ ] Verify payment succeeds
- [ ] Check membership is activated
- [ ] Verify email is sent
- [ ] Test cash payment option
- [ ] Verify admin can see payments

### 5. Admin Testing
- [ ] Login as admin
- [ ] View all payments
- [ ] Test payment refund (if needed)
- [ ] Approve cash payment

### 6. Production Preparation (When Ready)
- [ ] Get Square production credentials
- [ ] Complete Square account verification
- [ ] Test in sandbox thoroughly first
- [ ] Update `.env` with production credentials
- [ ] Change SQUARE_ENVIRONMENT=production
- [ ] Update Square SDK URL in index.html to production
- [ ] Test with real card (small amount, can refund)
- [ ] Monitor logs and Square Dashboard

## 🎯 Quick Test Script

After deployment, run these commands to verify:

```bash
# Check backend is running
curl http://localhost:8000/api/v1/payments/config/square

# Expected output (with your actual IDs):
# {
#   "application_id": "sandbox-sq0idb-...",
#   "location_id": "LXXX...",
#   "environment": "sandbox"
# }

# Check frontend is running
curl http://localhost:3000

# Check logs
docker-compose logs backend | grep -i square
```

## 📊 Testing Matrix

| Test Case | Expected Result | Status |
|-----------|----------------|--------|
| Square payment - valid card | Payment success, membership activated | [ ] |
| Square payment - declined card | Error shown, payment not created | [ ] |
| Cash payment | Payment pending, membership pending | [ ] |
| Admin approve cash payment | Membership activated | [ ] |
| Admin refund Square payment | Payment refunded in Square | [ ] |
| Email sent on activation | User receives email | [ ] |

## 🔍 Verification Commands

```bash
# Check Square SDK installed
docker-compose exec backend pip list | grep square

# Check configuration loaded
docker-compose exec backend python -c "from app.core.config import settings; print(settings.SQUARE_ENVIRONMENT)"

# Check database has payments
docker-compose exec mysql mysql -u "${DATABASE_USER}" -p -e "SELECT * FROM ${DATABASE_NAME}.payments LIMIT 5;"

# Check frontend files
ls -la frontend/src/components/SquarePayment.tsx
```

## 🐛 Common Issues & Solutions

| Issue | Solution |
|-------|----------|
| "Module not found: squareup" | Rebuild backend: `docker-compose build backend` |
| "SQUARE_APPLICATION_ID not found" | Add to `.env` and restart containers |
| Square SDK not loading | Check browser console, verify script tag in index.html |
| Payment fails with 401 | Check SQUARE_ACCESS_TOKEN is correct |
| Payment fails with location error | Verify SQUARE_LOCATION_ID matches your account |

## 📝 Notes

- All Square credentials are for **SANDBOX** by default
- No real money is charged in sandbox mode
- Test cards work only in sandbox environment
- Keep `.env` file secure and never commit to git
- Monitor Square Dashboard for transaction details
- Check backend logs for detailed error messages

## ✅ Sign-off

- [ ] All backend code implemented and tested
- [ ] All frontend code implemented and tested
- [ ] Documentation completed
- [ ] Deployment script created and tested
- [ ] Environment variables documented
- [ ] Ready for Square account setup
- [ ] Ready for deployment

---

**Implementation Status**: ✅ COMPLETE - Ready for Square credentials and deployment
**Next Step**: Follow SQUARE_QUICKSTART.md to get Square credentials and deploy