Payment Integration Overview

Gully Sports supports two enterprise-grade payment providers with seamless switching via feature flags. Choose the provider that best fits your business needs.

Supported Providers

Intuit QuickBooks Payments

Best For: Businesses already using QuickBooks for accounting

Key Features:

• 💳 Cards (Visa, Mastercard, Amex, Discover)
• 🍎 Apple Pay
• 🏦 ACH Bank Transfers
• 💰 PayPal & Venmo
• 📊 Direct QuickBooks integration
• 🧾 Automatic invoice generation
• 🔐 OAuth 2.0 authentication

Payment Methods Supported:

• Credit/Debit Cards
• Apple Pay
• ACH (Bank Transfer)
• PayPal
• Venmo

View Intuit Setup Guide →

Square

Best For: Modern businesses wanting flexible payment options

Key Features:

• 💳 Cards (Visa, Mastercard, Amex, Discover)
• 🍎 Apple Pay
• 🔵 Google Pay
• 🎁 Square Gift Cards
• 📱 Mobile-optimized
• ⚡ Fast integration
• 🔄 Real-time processing

Payment Methods Supported:

• Credit/Debit Cards
• Apple Pay
• Google Pay
• Square Gift Cards

View Square Setup Guide →

Quick Comparison

Feature	Intuit QuickBooks	Square
Cards	✅	✅
Apple Pay	✅	✅
Google Pay	❌	✅
ACH/Bank Transfer	✅	❌
PayPal	✅	❌
Venmo	✅	❌
Gift Cards	❌	✅ (Square only)
QuickBooks Integration	✅ Native	❌
Setup Complexity	Medium (OAuth)	Easy
Best For	Accounting users	General commerce

Switching Providers

Change payment providers instantly with a single environment variable:

# Use Intuit QuickBooks
NEXT_PUBLIC_PAYMENT_PROVIDER=intuit

# Use Square
NEXT_PUBLIC_PAYMENT_PROVIDER=square

The application automatically:

• ✅ Loads the correct SDK
• ✅ Renders appropriate payment forms
• ✅ Handles provider-specific logic
• ✅ Stores payment method correctly
• ✅ Updates checkout UI

Zero Code Changes

Switch providers without modifying code - just update the environment variable!

Setup Overview

Option 1: Intuit QuickBooks

1. Create Intuit Developer Account
2. Set Up OAuth - Configure QuickBooks connection
3. Get SDK Token - Obtain embedded payment token
4. Configure Environment Variables

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit
NEXT_PUBLIC_INTUIT_SDK_TOKEN="your-sdk-token"
NEXT_PUBLIC_INTUIT_COMPANY_ID="your-company-id"
NEXT_PUBLIC_COMPANY_NAME="Your Business Name"
INTUIT_CLIENT_ID="your-client-id"
INTUIT_CLIENT_SECRET="your-client-secret"
INTUIT_REDIRECT_URI="http://localhost:3000/api/admin/intuit/callback"
INTUIT_ENCRYPTION_KEY="your-32-character-encryption-key"

5. Complete OAuth Flow - Authorize via admin dashboard

Complete Intuit Setup Guide →

Option 2: Square

1. Create Square Developer Account
2. Get Application ID - Create Square application
3. Configure Environment Variables

NEXT_PUBLIC_PAYMENT_PROVIDER=square
NEXT_PUBLIC_SQUARE_APPLICATION_ID="your-application-id"
NEXT_PUBLIC_SQUARE_LOCATION_ID="your-location-id"
NEXT_PUBLIC_SQUARE_ENVIRONMENT="sandbox"  # or "production"
SQUARE_ACCESS_TOKEN="your-access-token"

4. Test Payment Flow - Use Square test cards

Complete Square Setup Guide →

Architecture

Payment Flow

User → Checkout Form
       ↓
       Payment Provider SDK (Client-Side)
       ↓
       Tokenization
       ↓
       API Route (/api/payments/submit)
       ↓
       Payment Provider API (Server-Side)
       ↓
       Database (Store Transaction)
       ↓
       Success Page

Security

• PCI Compliance: Payment data never touches your server
• Tokenization: Card details tokenized by provider SDKs
• HTTPS Only: All payment requests use SSL/TLS
• Idempotency: Prevent duplicate charges
• Server Validation: All payments verified server-side

File Structure

src/
├── app/
│   ├── checkout/
│   │   ├── CheckoutForm.tsx          # Provider router
│   │   ├── IntuitCheckoutForm.tsx    # Intuit implementation
│   │   └── SquareCheckoutForm.tsx    # Square implementation
│   └── api/
│       └── payments/
│           └── submit/
│               └── route.ts           # Unified payment endpoint
├── utils/
│   ├── featureFlags.ts               # Provider selection
│   ├── intuitPayments.ts             # Intuit logic
│   └── squarePayments.ts             # Square logic

Testing

Intuit Test Cards

Card Number: 4111111111111111
Expiry: Any future date
CVV: 123
ZIP: Any 5 digits

Square Test Cards

Success: 4111 1111 1111 1111
Decline: 4000 0000 0000 0002
CVV Required: 4002 0000 0000 0000

View Complete Testing Guide →

Common Issues

Payment Not Processing

Check:

• SDK loaded correctly (check browser console)
• API keys are valid and not expired
• Environment matches (sandbox vs production)
• Network requests not blocked

OAuth Failures (Intuit Only)

Check:

• Redirect URI matches exactly
• Client ID and secret are correct
• Token not expired (refresh if needed)
• Scopes include payment permissions

Google Pay Not Showing (Square)

Check:

• Using Chrome browser
• HTTPS enabled (localhost works)
• Amount is valid
• Location ID is correct

View Troubleshooting Guide →

Migration Between Providers

Switching from one provider to another? Follow our migration guide:

View Migration Guide →

Next Steps

Choose your payment provider and follow the setup guide:

• Intuit QuickBooks Setup →
• Square Setup →
• Feature Flags →
• Checkout Sessions →

---

Need help deciding? Contact support or check our Payment Provider Selection Guide.