Square Payments
This commit is contained in:
James Pattinson
164
SQUARE_QUICKSTART.md
Normal file
164
SQUARE_QUICKSTART.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 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! 🚀
|
||||
Reference in New Issue
Block a user