Skip to main content

Square Payments Integration Guide

This guide explains how to set up and use Square payments in your Gully Store application.

Overview​

The application now supports both Intuit and Square payment providers. You can switch between them using a feature flag without changing any code.

Prerequisites​

  1. A Square account (free to create at squareup.com)
  2. Square Application credentials
  3. Square Location ID

Getting Your Square Credentials​

Step 1: Create a Square Developer Account​

  1. Go to developer.squareup.com
  2. Sign in with your Square account or create a new one
  3. Navigate to the Developer Dashboard

Step 2: Create an Application​

  1. Click "+ Create App"
  2. Give your app a name (e.g., "Gully Store")
  3. Click "Create Application"

Step 3: Get Your Application ID​

  1. Open your newly created application

  2. Navigate to "Credentials" in the left sidebar

  3. You'll see two environments:

    • Sandbox (for testing)
    • Production (for live payments)

  4. Copy the following credentials:

    • Application ID (same for both sandbox and production)
    • Access Token (different for sandbox and production)

Step 4: Get Your Location ID​

  1. In the Square Developer Dashboard, go to "Locations"
  2. Copy the Location ID for the location where you want to process payments
  3. You can also get this via the API:
curl https://connect.squareupsandbox.com/v2/locations \
  -H 'Square-Version: 2024-01-18' \
  -H 'Authorization: Bearer YOUR_SANDBOX_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Configuration​

Environment Variables​

Add these environment variables to your .env.local file:

# Payment Provider Configuration
# Set to "square" to use Square payments, or "intuit" for Intuit payments
NEXT_PUBLIC_PAYMENT_PROVIDER=square

# Square Configuration (Public - used in browser)
NEXT_PUBLIC_SQUARE_APPLICATION_ID=your_square_application_id
NEXT_PUBLIC_SQUARE_LOCATION_ID=your_square_location_id
NEXT_PUBLIC_SQUARE_ENVIRONMENT=sandbox  # or "production"

# Square Configuration (Private - server-side only)
SQUARE_ACCESS_TOKEN=your_square_access_token
SQUARE_ENVIRONMENT=sandbox  # or "production"
SQUARE_LOCATION_ID=your_square_location_id
SQUARE_WEBHOOK_SIGNATURE_KEY=your_webhook_signature_key  # Optional, for webhooks

Example Configuration for Sandbox​

# Use Square for payments
NEXT_PUBLIC_PAYMENT_PROVIDER=square

# Public configuration
NEXT_PUBLIC_SQUARE_APPLICATION_ID=sandbox-sq0idb-XXXXXXXXXXXXXX
NEXT_PUBLIC_SQUARE_LOCATION_ID=LXXXXXXXXXXXXXX
NEXT_PUBLIC_SQUARE_ENVIRONMENT=sandbox

# Private configuration
SQUARE_ACCESS_TOKEN=EAAAXXXXXXXXXXXXXXXXXXXXXXXXXX
SQUARE_ENVIRONMENT=sandbox
SQUARE_LOCATION_ID=LXXXXXXXXXXXXXX

Example Configuration for Production​

# Use Square for payments
NEXT_PUBLIC_PAYMENT_PROVIDER=square

# Public configuration
NEXT_PUBLIC_SQUARE_APPLICATION_ID=sq0idp-XXXXXXXXXXXXXX
NEXT_PUBLIC_SQUARE_LOCATION_ID=LXXXXXXXXXXXXXX
NEXT_PUBLIC_SQUARE_ENVIRONMENT=production

# Private configuration
SQUARE_ACCESS_TOKEN=EAAAXXXXXXXXXXXXXXXXXXXXXXXXXX
SQUARE_ENVIRONMENT=production
SQUARE_LOCATION_ID=LXXXXXXXXXXXXXX

Switching Between Payment Providers​

To switch between Intuit and Square, simply change the NEXT_PUBLIC_PAYMENT_PROVIDER environment variable:

Use Square Payments​

NEXT_PUBLIC_PAYMENT_PROVIDER=square

Use Intuit Payments​

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit

That's it! The application will automatically use the correct payment form and API endpoints.

Payment Features​

Square Supports:​

  • ✅ Credit/Debit Card Payments
  • ✅ Apple Pay
  • ✅ Google Pay
  • ✅ Gift Cards
  • ✅ Secure card tokenization
  • ✅ PCI compliance (Square handles card data)

Intuit Supports:​

  • ✅ Credit/Debit Card Payments
  • ✅ ACH/Bank Transfers
  • ✅ PayPal
  • ✅ Venmo
  • ✅ Apple Pay

Testing​

Quick Google Pay Check​

If Google Pay is not showing up on Chrome:

  1. Check Console Logs:

    • Open DevTools (F12 or Cmd+Option+I)
    • Look for "Google Pay initialized successfully" or error messages

  2. Verify Requirements:

    • Using Chrome (version 61+)
    • Signed into Chrome with Google account
    • At least one payment method at pay.google.com
    • Google Pay enabled in Square Dashboard
    • Site on HTTPS or localhost

  3. See Detailed Troubleshooting:

    • Refer to GOOGLE_PAY_TROUBLESHOOTING.md for complete guide
    • Common fix: Sign into Chrome and add payment method to Google Pay

Sandbox Mode (Testing)​

Square provides test card numbers for sandbox testing:

Card BrandCard NumberCVVExpiry
Visa4111 1111 1111 1111AnyAny future
Mastercard5105 1051 0510 5100AnyAny future
Amex3400 000000 00009AnyAny future
Discover6011 0000 0000 0004AnyAny future

Note: Always use sandbox credentials during development!

Test Payment Flow​

  1. Set NEXT_PUBLIC_PAYMENT_PROVIDER=square
  2. Use sandbox credentials
  3. Go to /shop and add items to cart
  4. Proceed to checkout
  5. Use a test card number
  6. Complete the payment
  7. Verify in Square Dashboard → Payments (Sandbox mode)

Architecture​

File Structure​

src/
├── utils/
│   ├── squarePayments.ts          # Square API integration
│   ├── intuitPayments.ts          # Intuit API integration
│   ├── paymentProvider.ts         # Abstraction layer
│   └── featureFlags.ts            # Feature flag configuration
├── app/
│   ├── checkout/
│   │   ├── CheckoutForm.tsx       # Router component
│   │   ├── SquareCheckoutForm.tsx # Square-specific form
│   │   └── IntuitCheckoutForm.tsx # Intuit-specific form
│   └── api/
│       └── payments/
│           ├── submit/
│           │   └── route.ts       # Unified payment submission
│           └── square/
│               ├── initiate/
│               │   └── route.ts   # Square initiation
│               └── submit/
│                   └── route.ts   # Square submission

Payment Flow​

Square Payment Flow:​

  1. Frontend loads Square Web Payments SDK
  2. User enters card information
  3. SDK tokenizes card (PCI-compliant)
  4. Frontend sends token to /api/payments/submit
  5. Backend processes payment with Square API
  6. Backend stores transaction in database
  7. Frontend redirects to success page

Intuit Payment Flow:​

  1. Frontend loads Intuit Embedded Payments SDK
  2. User selects payment method
  3. SDK tokenizes payment information
  4. Frontend sends token to /api/payments/submit
  5. Backend processes payment with Intuit API
  6. Backend stores transaction in database
  7. Frontend redirects to success page

API Endpoints​

Common Endpoints​

  • POST /api/payments/submit - Process payment (supports both providers)

Square-Specific Endpoints​

  • POST /api/payments/square/initiate - Initialize Square payment
  • POST /api/payments/square/submit - Submit Square payment

Intuit-Specific Endpoints​

  • POST /api/payments/paypal/initiate - Initialize PayPal payment

Database Schema​

Payments are stored in the Payment model:

model Payment {
  id            String   @id @default(cuid())
  transactionId String   @unique
  amount        Float
  currency      String   @default("USD")
  paymentMethod String   // e.g., "square_card", "paypal", "intuit_card"
  status        String   // e.g., "completed", "pending", "failed"
  productName   String?
  metadata      Json?
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
}

Security Best Practices​

Environment Variables​

  • ✅ NEVER commit .env.local to version control
  • ✅ Keep SQUARE_ACCESS_TOKEN secret (server-side only)
  • ✅ Use different credentials for sandbox and production
  • ✅ Rotate access tokens regularly
  • ✅ Use environment-specific variables in deployment

PCI Compliance​

  • ✅ NEVER store raw card numbers
  • ✅ Use Square's tokenization (they handle PCI compliance)
  • ✅ Always use HTTPS in production
  • ✅ Validate payments server-side

Production Checklist​

Before going live:

  • Change NEXT_PUBLIC_SQUARE_ENVIRONMENT to production
  • Use production Square credentials
  • Test end-to-end payment flow
  • Verify webhook configuration (if using webhooks)
  • Enable HTTPS
  • Set up error monitoring
  • Configure proper CORS settings
  • Review Square Dashboard settings

Troubleshooting​

"Payment configuration is missing"​

Problem: Square credentials not found

Solution:

  • Verify environment variables are set correctly
  • Restart your development server
  • Check that variable names start with NEXT_PUBLIC_ for client-side access

"Payment tokenization failed"​

Problem: Card validation failed

Solution:

  • In sandbox: Use test card numbers
  • Check card number, expiry, and CVV are valid
  • Ensure card form is fully loaded before submission

"Location ID not configured"​

Problem: Missing or invalid location ID

Solution:

  • Get your location ID from Square Dashboard
  • Set NEXT_PUBLIC_SQUARE_LOCATION_ID environment variable
  • Restart your server

"Access token invalid"​

Problem: Wrong or expired access token

Solution:

  • Verify you're using the correct access token for your environment
  • Regenerate access token in Square Dashboard if needed
  • Ensure SQUARE_ACCESS_TOKEN is set on the server

Webhooks (Optional)​

Square can send webhooks for payment events:

Setup Webhooks​

  1. Go to Square Dashboard → Webhooks
  2. Create a webhook endpoint: https://yourdomain.com/api/webhooks/square
  3. Subscribe to events:
    • payment.created
    • payment.updated
    • refund.created
  4. Copy the webhook signature key
  5. Add to .env.local:
SQUARE_WEBHOOK_SIGNATURE_KEY=your_webhook_signature_key

Webhook Verification​

The squarePayments.ts utility includes a verifySquareWebhook() function for signature verification.

Support and Resources​

Square Resources​

Community​

Comparison: Square vs Intuit​

FeatureSquareIntuit
Credit/Debit Cards✅✅
ACH/Bank Transfer❌✅
PayPal❌✅
Venmo❌✅
Apple Pay✅✅
Google Pay✅❌
Gift Cards✅❌
Invoicing✅✅
Recurring Payments✅✅
Customer Profiles✅✅
POS Integration✅❌
QuickBooks Integration❌✅
Transaction Fees2.9% + 30¢2.9% + 25¢
Monthly Fee$0$0

Choose Square if you:

  • Want POS integration
  • Need gift card support
  • Prefer Google Pay
  • Have physical locations

Choose Intuit if you:

  • Use QuickBooks
  • Need ACH payments
  • Want PayPal/Venmo support
  • Need comprehensive accounting integration

Migration Between Providers​

To migrate from Intuit to Square (or vice versa):

  1. Set up new provider credentials
  2. Change NEXT_PUBLIC_PAYMENT_PROVIDER environment variable
  3. Test in sandbox/staging environment
  4. Deploy to production
  5. Monitor initial transactions

Note: Existing payment records remain unchanged. The provider only affects new transactions.

Next Steps​

  1. ✅ Set up Square account
  2. ✅ Get credentials
  3. ✅ Configure environment variables
  4. ✅ Test in sandbox mode
  5. ✅ Switch to production when ready

Need help? Check the Getting Started Guide or create an issue in the repository.