230 lines
7.7 KiB
Markdown
230 lines
7.7 KiB
Markdown
# 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)
|