# Square Payment Integration - Quick Start

## ✅ Implementation Complete

Square payment processing has been successfully integrated into your membership portal!

## 🎯 What You Can Do Now

Users can now pay for memberships using:
1. **Credit/Debit Cards** - Processed securely through Square
2. **Cash** - Recorded as pending, requires admin approval

## 🚀 Quick Start Guide

### Step 1: Get Square Credentials (5 minutes)

1. Go to [Square Developer Portal](https://developer.squareup.com/)
2. Sign up or log in
3. Create a new application or select existing one
4. Copy these credentials from the **Sandbox** tab:
   - Sandbox Access Token
   - Sandbox Application ID  
   - Sandbox Location ID

### Step 2: Configure Environment Variables

Edit your `.env` file and add:

```bash
SQUARE_ACCESS_TOKEN=EAAAl...your-sandbox-token...
SQUARE_ENVIRONMENT=sandbox
SQUARE_LOCATION_ID=LXXX...your-location-id...
SQUARE_APPLICATION_ID=sandbox-sq0idb-...your-app-id...
```

### Step 3: Deploy the Changes

Run the deployment script:

```bash
./deploy-square.sh
```

Or manually:

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

### Step 4: Test It Out!

1. Open http://localhost:3000
2. Register/login
3. Go to "Setup Membership"
4. Select a tier
5. Choose "Credit/Debit Card"
6. Use test card: **4111 1111 1111 1111**
   - CVV: 111
   - Expiry: 12/25
   - Postal Code: 12345

## 📁 Files Changed/Created

### Backend
- ✅ `backend/app/services/square_service.py` - NEW
- ✅ `backend/app/api/v1/payments.py` - UPDATED
- ✅ `backend/app/schemas/schemas.py` - UPDATED
- ✅ `backend/app/core/config.py` - UPDATED
- ✅ `backend/requirements.txt` - UPDATED

### Frontend  
- ✅ `frontend/src/components/SquarePayment.tsx` - NEW
- ✅ `frontend/src/components/MembershipSetup.tsx` - UPDATED
- ✅ `frontend/index.html` - UPDATED

### Configuration
- ✅ `.env.example` - UPDATED
- ✅ `SQUARE_PAYMENT_SETUP.md` - NEW (detailed setup guide)
- ✅ `SQUARE_IMPLEMENTATION.md` - NEW (implementation details)
- ✅ `deploy-square.sh` - NEW (deployment helper)

## 🔧 Key Features

- ✅ Secure card payment processing via Square
- ✅ PCI-compliant (card data never touches your server)
- ✅ Automatic membership activation on payment success
- ✅ Email confirmations
- ✅ Admin refund capability
- ✅ Payment history tracking
- ✅ Sandbox testing support
- ✅ Production-ready

## 📊 Payment Flow

```
User → Select Tier → Choose Payment Method
   ↓
   Square: Enter Card → Tokenize → Process → ✅ Active Membership
   Cash: Confirm → ⏳ Pending → Admin Approval → ✅ Active Membership
```

## 🧪 Test Cards (Sandbox Only)

| Card                | Result           |
|---------------------|------------------|
| 4111 1111 1111 1111 | ✅ Success       |
| 4000 0000 0000 0002 | ❌ Declined      |
| 5105 1051 0510 5100 | ✅ Success (MC)  |

## 📚 Documentation

- **Setup Guide**: `SQUARE_PAYMENT_SETUP.md` - Complete setup instructions
- **Implementation**: `SQUARE_IMPLEMENTATION.md` - Technical details
- **Square Docs**: https://developer.squareup.com/docs/web-payments/overview

## 🐛 Troubleshooting

### Backend won't start?
```bash
docker-compose logs backend
```
Check for missing dependencies or configuration errors.

### Square config endpoint fails?
Make sure `SQUARE_APPLICATION_ID` is in your `.env` file.

### Payment processing fails?
1. Verify all Square credentials are correct
2. Ensure `SQUARE_ENVIRONMENT` matches your token type
3. Check backend logs for detailed errors

### Can't see payment form?
Check browser console - Square SDK must load successfully.

## 🎓 Going Live

When ready for production payments:

1. ✅ Get Square production credentials
2. ✅ Update `.env` with production values
3. ✅ Change `SQUARE_ENVIRONMENT=production`
4. ✅ Update Square SDK URL in `index.html` to production
5. ✅ Test thoroughly with real cards (can be refunded)
6. ✅ Monitor Square Dashboard and application logs

## 💡 Tips

- **Always test in sandbox first** - No risk, unlimited testing
- **Keep credentials secure** - Never commit `.env` to git
- **Monitor transactions** - Check Square Dashboard regularly
- **Test refunds** - Make sure admin refund flow works
- **Email notifications** - Verify users receive payment confirmations

## 🆘 Need Help?

1. Check `SQUARE_PAYMENT_SETUP.md` for detailed instructions
2. Review Square's documentation
3. Check application logs: `docker-compose logs -f backend`
4. Contact Square support for payment-specific issues

---

**Ready to accept payments?** Just follow Steps 1-4 above! 🚀