165 lines
4.5 KiB
Markdown
165 lines
4.5 KiB
Markdown
# 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! 🚀
|