Skip to main content

Payment Provider Implementation Summary

Overview​

This document summarizes the implementation of dual payment provider support (Intuit and Square) with a feature flag to switch between them.

What Was Implemented​

1. Square SDK Integration ✅​

  • Package: Installed square npm package
  • Location: node_modules/square
  • Version: Latest stable version

2. Payment Provider Utilities ✅​

Square Payments (src/utils/squarePayments.ts)​

  • processSquarePayment() - Process payments through Square API
  • createSquareCustomer() - Create customer profiles
  • createSquareOrder() - Create orders in Square
  • verifySquareWebhook() - Webhook signature verification
  • Helper functions for getting configuration values

Payment Provider Abstraction (src/utils/paymentProvider.ts)​

  • getPaymentConfig() - Get configuration for active provider
  • getPaymentProviderInfo() - Get provider information
  • validatePaymentConfig() - Validate provider setup
  • getPaymentSDKUrl() - Get SDK URL for active provider
  • Unified interface for both providers

3. Feature Flag System ✅​

File: src/utils/featureFlags.ts

Added payment provider configuration:

export type PaymentProvider = "intuit" | "square";
export const PAYMENT_PROVIDER: PaymentProvider =
  (process.env.NEXT_PUBLIC_PAYMENT_PROVIDER as PaymentProvider) || "intuit";

Helper functions:

  • getPaymentProvider() - Get current provider
  • isIntuitPayments() - Check if using Intuit
  • isSquarePayments() - Check if using Square

4. Checkout Forms ✅​

Router Component (src/app/checkout/CheckoutForm.tsx)​

  • Routes to correct checkout form based on PAYMENT_PROVIDER
  • Seamless switching between providers

Intuit Form (src/app/checkout/IntuitCheckoutForm.tsx)​

  • Renamed from original CheckoutForm.tsx
  • Intuit Embedded Payments SDK integration
  • Supports: Cards, ACH, PayPal, Venmo, Apple Pay

Square Form (src/app/checkout/SquareCheckoutForm.tsx)​

  • New Square Web Payments SDK integration
  • Supports: Cards, Apple Pay, Google Pay, Gift Cards
  • Modern card input with tokenization

5. API Routes ✅​

Unified Submit Endpoint (src/app/api/payments/submit/route.ts)​

  • Updated to handle both Intuit and Square
  • Auto-detects provider based on request parameters
  • Backward compatible with existing Intuit implementation

Square-Specific Routes​

  • src/app/api/payments/square/initiate/route.ts - Initialize Square payment
  • src/app/api/payments/square/submit/route.ts - Submit Square payment

6. Documentation ✅​

Created comprehensive documentation:

Square Payments Guide (SQUARE_PAYMENTS_GUIDE.md)​

  • Complete setup instructions
  • Credential acquisition guide
  • Environment variable configuration
  • Testing guide with test card numbers
  • Architecture overview
  • Troubleshooting section
  • Security best practices
  • Comparison: Square vs Intuit

Feature Flags Update (FEATURE_FLAGS.md)​

  • Payment provider configuration section
  • Instructions for switching providers
  • List of what changes when switching

README Updates (README.md)​

  • Updated payment integration section
  • Added dual provider information
  • Added environment variable examples
  • Added documentation links

Environment Variables​

Payment Provider Selection​

NEXT_PUBLIC_PAYMENT_PROVIDER=square  # or "intuit" (default)

Square Configuration​

# Public (client-side)
NEXT_PUBLIC_SQUARE_APPLICATION_ID=your_app_id
NEXT_PUBLIC_SQUARE_LOCATION_ID=your_location_id
NEXT_PUBLIC_SQUARE_ENVIRONMENT=sandbox

# Private (server-side)
SQUARE_ACCESS_TOKEN=your_access_token
SQUARE_ENVIRONMENT=sandbox
SQUARE_LOCATION_ID=your_location_id
SQUARE_WEBHOOK_SIGNATURE_KEY=optional_webhook_key

Intuit Configuration (existing)​

# Public (client-side)
NEXT_PUBLIC_INTUIT_SDK_TOKEN=your_sdk_token
NEXT_PUBLIC_INTUIT_COMPANY_ID=your_company_id
NEXT_PUBLIC_COMPANY_NAME=Your Business
NEXT_PUBLIC_COMPANY_WEBSITE=yourdomain.com

# Private (server-side)
INTUIT_CLIENT_ID=your_client_id
INTUIT_CLIENT_SECRET=your_client_secret
INTUIT_REDIRECT_URI=your_callback_url

File Structure​

src/
├── utils/
│   ├── squarePayments.ts          # NEW: Square API integration
│   ├── intuitPayments.ts          # Existing Intuit integration
│   ├── paymentProvider.ts         # NEW: Abstraction layer
│   └── featureFlags.ts            # UPDATED: Added payment provider
├── app/
│   ├── checkout/
│   │   ├── CheckoutForm.tsx       # UPDATED: Router component
│   │   ├── SquareCheckoutForm.tsx # NEW: Square checkout form
│   │   └── IntuitCheckoutForm.tsx # RENAMED: From CheckoutForm.tsx
│   └── api/
│       └── payments/
│           ├── submit/
│           │   └── route.ts       # UPDATED: Multi-provider support
│           └── square/
│               ├── initiate/      # NEW
│               │   └── route.ts
│               └── submit/        # NEW
│                   └── route.ts

Documentation:
├── SQUARE_PAYMENTS_GUIDE.md       # NEW: Complete Square guide
├── FEATURE_FLAGS.md               # UPDATED: Payment provider info
└── README.md                      # UPDATED: Payment section

How to Use​

Switch to Square Payments​

  1. Set environment variable:

    NEXT_PUBLIC_PAYMENT_PROVIDER=square

  2. Add Square credentials (see SQUARE_PAYMENTS_GUIDE.md)

  3. Restart development server:

    npm run dev

  4. Test checkout flow:

    • Navigate to /shop
    • Add items and proceed to checkout
    • Square checkout form will automatically load

Switch to Intuit Payments​

  1. Set environment variable:

    NEXT_PUBLIC_PAYMENT_PROVIDER=intuit

    Or simply omit the variable (Intuit is default)

  2. Ensure Intuit credentials are configured

  3. Restart development server

  4. Test checkout flow - Intuit form will load

Testing​

Square Sandbox Testing​

Test card numbers:

  • Visa: 4111 1111 1111 1111
  • Mastercard: 5105 1051 0510 5100
  • Amex: 3782 822463 10005
  • CVV: Any 3-4 digits
  • Expiry: Any future date

Intuit Sandbox Testing​

Use Intuit's test credentials and test cards (see INTUIT_OAUTH_GUIDE.md)

Key Features​

✅ Seamless Switching​

  • Change one environment variable
  • No code changes required
  • Automatic form routing

✅ Backward Compatibility​

  • Existing Intuit implementation unchanged
  • All existing API endpoints still work
  • Database schema supports both providers

✅ Type Safety​

  • Full TypeScript support
  • Type-safe provider configuration
  • Compile-time validation

✅ PCI Compliance​

  • Both SDKs handle card tokenization
  • No raw card data touches your server
  • Secure payment processing

✅ Comprehensive Documentation​

  • Setup guides for both providers
  • Environment variable documentation
  • Troubleshooting guides
  • Security best practices

Payment Flow​

Square Flow:​

  1. User enters payment info
  2. Square SDK tokenizes card
  3. Token sent to /api/payments/submit
  4. Server processes with Square API
  5. Transaction stored in database
  6. User redirected to success page

Intuit Flow:​

  1. User selects payment method
  2. Intuit SDK tokenizes payment
  3. Token sent to /api/payments/submit
  4. Server processes with Intuit API
  5. Transaction stored in database
  6. User redirected to success page

Database​

Both providers use the same Payment model:

model Payment {
  id            String   @id @default(cuid())
  transactionId String   @unique
  amount        Float
  currency      String   @default("USD")
  paymentMethod String   // "square_card", "intuit_card", "paypal", etc.
  status        String
  productName   String?
  metadata      Json?    // Provider-specific data
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
}

Security Considerations​

✅ Implemented​

  • Environment variable separation (public vs private)
  • Server-side token validation
  • PCI-compliant tokenization
  • Secure credential storage

📋 Recommendations​

  • Use different credentials for sandbox/production
  • Rotate access tokens regularly
  • Enable HTTPS in production
  • Set up webhook signature verification
  • Monitor failed payment attempts
  • Implement rate limiting

Performance​

Optimizations​

  • Lazy loading of payment SDKs
  • Code splitting for provider-specific components
  • Efficient database queries
  • Minimal API calls

Metrics to Monitor​

  • Payment success rate
  • SDK load time
  • API response time
  • Error rates by provider

Troubleshooting​

Common Issues​

  1. "Payment configuration is missing"

    • Check environment variables are set
    • Restart development server
    • Verify variable names (NEXTPUBLIC prefix for client-side)

  2. "Provider not loading"

    • Check NEXT_PUBLIC_PAYMENT_PROVIDER value
    • Must be exactly "intuit" or "square"
    • Clear Next.js cache: rm -rf .next

  3. "Payment tokenization failed"

    • In sandbox: use test card numbers
    • Check card details are valid
    • Verify SDK loaded successfully

Future Enhancements​

Potential additions:

  • Additional payment providers (Stripe, PayPal Direct)
  • Saved payment methods
  • Recurring payments
  • Subscription management
  • Multi-currency support
  • Advanced fraud detection
  • Payment analytics dashboard

Migration Guide​

From Intuit-only to Dual Provider​

The implementation is backward compatible. Existing Intuit setup continues to work without any changes. To add Square:

  1. Install Square SDK (already done)
  2. Add Square environment variables
  3. Set NEXT_PUBLIC_PAYMENT_PROVIDER=square when ready
  4. Test thoroughly in sandbox
  5. Deploy to production

Rolling Back​

To revert to Intuit-only:

  1. Set NEXT_PUBLIC_PAYMENT_PROVIDER=intuit
  2. Restart server
  3. Square components won't be loaded

Conclusion​

✅ Fully Implemented: Square payment integration with feature flag switching ✅ Production Ready: Secure, tested, and documented ✅ Maintainable: Clean architecture with abstraction layer ✅ Scalable: Easy to add more providers in the future

For detailed setup instructions, see:

  • Square: SQUARE_PAYMENTS_GUIDE.md
  • Intuit: INTUIT_OAUTH_GUIDE.md
  • Feature Flags: FEATURE_FLAGS.md
  • General Setup: README.md