Skip to main content

Intuit Embedded Payments - Complete Integration Guide

Status: ✅ Complete and Ready for Testing
Last Updated: October 2025
Version: 1.0.0

📋 Table of Contents​

  1. Overview
  2. Features
  3. Implementation Summary
  4. Quick Start
  5. Setup Instructions
  6. Testing
  7. Architecture
  8. Customization
  9. Troubleshooting
  10. Production Deployment
  11. References

Overview​

The Intuit QuickBooks Embedded Payment SDK has been successfully integrated into your Gully Store application. This guide provides complete documentation for setup, testing, customization, and production deployment.

Supported Payment Methods​

  • 💳 Credit Cards (Visa, Mastercard, Amex, Discover)
  • 💳 Debit Cards
  • 🏦 ACH (Bank Account)
  • 💰 PayPal
  • 💵 Venmo
  • 🍎 Apple Pay

Key Features​

  • ✅ Secure payment tokenization (PCI compliant)
  • ✅ Real-time payment processing
  • ✅ Automatic OAuth token refresh
  • ✅ Transaction history in database
  • ✅ Multiple payment method support
  • ✅ Responsive Stripe-like checkout UI
  • ✅ Error handling and validation
  • ✅ Cart persistence with localStorage
  • ✅ Success confirmation page

Implementation Summary​

What Was Built​

1. URL Centralization​

File: src/utils/intuitConstants.ts

All Intuit-related URLs are centralized in one place:

  • OAuth URLs (authorization, token exchange)
  • QuickBooks API URLs (accounting, payments)
  • Embedded Payment SDK URLs (sandbox & production)
  • Internal API routes
  • Documentation URLs

Benefits:

  • Easy to update if URLs change
  • Clear organization
  • Type-safe helper functions
  • Environment-specific configuration

2. Checkout Flow​

Pages Created:

  1. /checkout - Main checkout page with embedded payment form
  2. /checkout/success - Success confirmation page with cart clearing

Features:

  • Stripe-inspired two-column layout
  • Order summary display with sticky sidebar
  • Multiple payment methods
  • Real-time payment processing
  • Error handling with user-friendly messages
  • Loading states and animations
  • Cart persistence across page refreshes
  • Automatic cart clearing on successful payment

3. API Routes​

/api/payments/submit (POST)

  • Processes all payment types (cards, ACH, Apple Pay, PayPal)
  • OAuth token validation
  • Intuit Payments API integration
  • Database transaction logging
  • Comprehensive error handling

/api/payments/paypal/initiate (POST)

  • Creates PayPal order
  • Returns order ID for SDK
  • Integrates with Intuit PayPal flow

4. Database Schema​

Payment Model:

model Payment {
  id              String   @id @default(cuid())
  transactionId   String   @unique
  amount          Decimal
  currency        String   @default("USD")
  paymentMethod   String
  status          String   @default("pending")
  productName     String?
  metadata        Json?
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt

  @@index([transactionId])
  @@index([status])
}

5. Shopping Cart Enhancement​

Cart Persistence:

  • Cart saved to localStorage automatically
  • Email address persisted
  • Survives page refreshes and navigation
  • Only cleared after successful payment

Quick Start​

1. Set Environment Variables​

Add to your .env.local:

# Intuit Embedded Payment SDK (Client-side)
NEXT_PUBLIC_INTUIT_SDK_TOKEN="your-sdk-token-here"
NEXT_PUBLIC_INTUIT_COMPANY_ID="your-realm-id-here"
NEXT_PUBLIC_COMPANY_NAME="Gully Store"
NEXT_PUBLIC_COMPANY_WEBSITE="gullystore.com"

# Existing OAuth credentials (Server-side)
INTUIT_CLIENT_ID="your-client-id"
INTUIT_CLIENT_SECRET="your-client-secret"
INTUIT_ENCRYPTION_KEY="your-32-character-encryption-key"

⚠️ Important: Get NEXT_PUBLIC_INTUIT_SDK_TOKEN from your Intuit integration administrator.

2. Run Database Migration​

# Generate Prisma client
npx prisma generate

# Apply migration
npx prisma migrate deploy

3. Start Development Server​

npm run dev

4. Test the Flow​

  1. Visit http://localhost:3000/shop
  2. Add items to cart
  3. Enter email address
  4. Click "Proceed to Checkout"
  5. Use test card: 4111111111111111, CVV: 123
  6. Complete payment

Setup Instructions​

Prerequisites​

  1. QuickBooks Online account
  2. Intuit Developer account
  3. OAuth 2.0 credentials configured (see OAuth Setup Guide)
  4. Embedded Payment SDK token from Intuit

Detailed Setup​

Step 1: Get Your SDK Token​

Contact your Intuit integration administrator to obtain:

  • SDK Token (NEXT_PUBLIC_INTUIT_SDK_TOKEN)
  • Company/Realm ID (NEXT_PUBLIC_INTUIT_COMPANY_ID)

Step 2: Configure Environment Variables​

The NEXT_PUBLIC_ prefix makes these variables available in the browser. The SDK token is different from OAuth credentials and is scoped to your application.

Step 3: Verify OAuth Setup​

  1. Navigate to /admin in your application
  2. Check the "Intuit QuickBooks Integration" section
  3. Ensure it shows "Connected"
  4. If not connected, click "Connect to QuickBooks"

Step 4: Test the Integration​

Start with sandbox mode (automatically configured) before going to production.

Testing​

Test Credentials (Sandbox)​

Credit Cards​

Card TypeNumberCVVExpiry
Visa4111111111111111123Any future date
Mastercard5500000000000004123Any future date
Amex3400000000000091234Any future date

ACH (Bank Account)​

  • Routing Number: 021000021
  • Account Number: Any 9-17 digits (e.g., 123456789)

PayPal​

Use your PayPal sandbox credentials from developer.paypal.com

Testing Flow​

  1. Shop Page - Browse products, add to cart, enter email
  2. Checkout Page - Review order, select payment method, enter details
  3. Payment Processing - SDK tokenizes, backend processes, database logs
  4. Success Page - Confirmation shown, cart cleared, transaction ID displayed

Architecture​

Payment Flow​

┌─────────────┐
│  Customer   │
│  Shop Page  │
└──────┬──────┘
       │ Add to cart, enter email
       │ (Saved to localStorage)
       ↓
┌──────────────────┐
│  Checkout Page   │
│ (CheckoutForm)   │
└──────┬───────────┘
       │ Load Embedded SDK
       ↓
┌──────────────────────┐
│ Intuit Payment SDK   │
│ (iframe tokenization)│
└──────┬───────────────┘
       │ Submit payment
       ↓
┌──────────────────────────┐
│ /api/payments/submit     │
└──────┬───────────────────┘
       │ Get OAuth token
       ↓
┌──────────────────────────┐
│ Intuit Payments API      │
│ (Process charge)         │
└──────┬───────────────────┘
       │ Save to database
       ↓
┌──────────────────────────┐
│ Payment table            │
└──────┬───────────────────┘
       │ Return success
       ↓
┌──────────────────────────┐
│ Success Page             │
│ (Clear localStorage)     │
└──────────────────────────┘

Technology Stack​

  • Frontend: Next.js 14, React, TypeScript
  • Payment SDK: Intuit Embedded Payment SDK
  • Backend: Next.js API Routes
  • Database: CockroachDB (Prisma ORM)
  • Authentication: Supabase Auth + Intuit OAuth 2.0
  • Payment Processing: Intuit QuickBooks Payments API

Project Structure​

src/
├── app/
│   ├── checkout/
│   │   ├── page.tsx                    # Checkout wrapper
│   │   ├── CheckoutForm.tsx            # Main checkout form
│   │   └── success/
│   │       └── page.tsx                # Success page
│   ├── api/
│   │   └── payments/
│   │       ├── submit/
│   │       │   └── route.ts            # Payment processing
│   │       └── paypal/
│   │           └── initiate/
│   │               └── route.ts        # PayPal initiation
│   └── shop/
│       └── ShopForm.tsx                # Cart & checkout
├── utils/
│   ├── intuitConstants.ts              # ✨ ALL URLs HERE
│   ├── intuitOAuth.ts                  # OAuth management
│   └── intuitPayments.ts               # Payment utilities
└── components/
    └── IntuitOAuthSection.tsx          # OAuth UI

prisma/
├── schema.prisma                        # Payment model
└── migrations/
    └── 20251011100000_add_payment_model/
        └── migration.sql

Security​

PCI Compliance​

  • ✅ No card data touches your server - SDK tokenizes before submission
  • ✅ Encrypted OAuth tokens - Stored with AES-256 encryption
  • ✅ HTTPS required - Enforced in production
  • ✅ Secure token storage - Database encrypted at rest

Best Practices​

  1. Token Encryption: All sensitive tokens encrypted
  2. Automatic Refresh: OAuth tokens refresh before expiration
  3. Idempotent Requests: Request-Id headers prevent duplicate charges
  4. Input Validation: All inputs validated before processing
  5. Error Handling: Comprehensive error handling throughout
  6. Audit Trail: All transactions logged in database

Customization​

Changing Payment Methods​

Edit src/app/checkout/CheckoutForm.tsx:

enabledPaymentMethods: ["card", "bank", "payPal", "venmo", "applePay"];

Remove or reorder as needed.

Styling the Checkout​

The payment form is in an iframe (styled by Intuit), but you can customize:

  1. Container styling and layout
  2. Submit button appearance
  3. Success/Error messages
  4. Order summary display

Adding Order Processing​

After successful payment in /api/payments/submit/route.ts:

// Create order record
await prisma.order.create({
  data: {
    userId: userId,
    totalPrice: amount,
    items: {
      create: orderItems,
    },
  },
});

// Send confirmation email
await sendConfirmationEmail(email, transactionId);

// Update inventory
await updateInventory(productId, quantity);

Troubleshooting​

SDK Not Loading​

Problem: Payment form doesn't appear

Solutions:

  1. Check browser console for errors
  2. Verify NEXT_PUBLIC_INTUIT_SDK_TOKEN is set correctly
  3. Ensure NEXT_PUBLIC_INTUIT_COMPANY_ID matches your QuickBooks account
  4. Check Network tab - SDK script should load from Intuit

Payment Processing Not Available​

Problem: Error message on submit

Solutions:

  1. Check OAuth connection in /admin
  2. Ensure access token hasn't expired (auto-refresh should handle this)
  3. Verify all environment variables are set
  4. Check server logs for detailed errors

Payment Fails​

Problem: Payment submission returns error

Solutions:

  1. Verify test card numbers are correct for sandbox
  2. Check that amount is valid (> 0)
  3. Review API response in browser console
  4. Check server logs for Intuit API errors

Database Connection Error​

Problem: "Failed to save payment"

Solutions:

  1. Verify DATABASE_URL is correct
  2. Run npx prisma generate
  3. Apply migrations with npx prisma migrate deploy
  4. Check database connection and credentials

Cart Not Persisting​

Problem: Cart clears on page refresh

Solutions:

  1. Check browser localStorage is enabled
  2. Verify no browser extensions blocking localStorage
  3. Check console for localStorage errors
  4. Ensure isLoaded state is working properly

Production Deployment​

Pre-Deployment Checklist​

  • Get production SDK token from Intuit
  • Update environment variables for production
  • Change SDK environment to "prod" in CheckoutForm.tsx
  • Update SDK URL to production in intuitConstants.ts
  • Test with real payment methods
  • Set up error monitoring (Sentry, LogRocket, etc.)
  • Configure webhook handlers (optional)
  • Update redirect URIs in Intuit dashboard
  • Enable HTTPS (required)
  • Review security settings
  • Test cart persistence
  • Verify email notifications work

Production Configuration​

1. Update CheckoutForm.tsx​

env: "prod", // Change from "sandbox"

2. Update SDK URL (if needed)​

// In CheckoutForm.tsx
import { INTUIT_EMBEDDED_PAYMENT_SDK_PRODUCTION_URL } from "@/utils/intuitConstants";

3. Environment Variables​

NODE_ENV=production
NEXT_PUBLIC_INTUIT_SDK_TOKEN="prod-token-here"
NEXT_PUBLIC_INTUIT_COMPANY_ID="production-realm-id"

4. Testing Production​

  1. Test with small real transactions
  2. Monitor logs closely
  3. Verify database records
  4. Check cart clearing works
  5. Test all payment methods
  6. Verify email receipts

References​

Documentation​

Environment URLs​

Sandbox:

  • SDK: https://sdk.embedded-payments.a.intuit.com/staging/embedded-payment-ui-sdk.en.js
  • OAuth: https://appcenter.intuit.com/connect/oauth2

Production:

  • SDK: https://sdk.embedded-payments.a.intuit.com/embedded-payment-ui-sdk.en.js
  • OAuth: https://appcenter.intuit.com/connect/oauth2

API Endpoints​

Internal:

  • /api/payments/submit - Process payments
  • /api/payments/paypal/initiate - Initiate PayPal
  • /api/admin/intuit/auth - Start OAuth flow
  • /api/admin/intuit/callback - OAuth callback
  • /api/admin/intuit/status - Check OAuth status
  • /api/admin/intuit/refresh - Refresh tokens

Support​

For Issues​

  1. Setup Problems: Check this guide and environment variables
  2. Payment Errors: Review browser console and server logs
  3. OAuth Issues: See INTUIT_OAUTH_GUIDE.md
  4. SDK Questions: Contact Intuit Developer Support
  5. Database Issues: Check Prisma documentation

Getting Help​

  • Documentation: Review this guide thoroughly
  • Browser Console: Check for JavaScript errors
  • Server Logs: Review API route logs
  • Intuit Support: Contact for SDK/API issues
  • Community: Intuit Developer Community forums

Success Metrics​

Implementation Complete ✅​

  • URL centralization in constants file
  • Checkout page with SDK integration
  • Payment submission API
  • PayPal initiation API
  • Database Payment model
  • Success page with cart clearing
  • Cart persistence with localStorage
  • Error handling and validation
  • Loading states and animations
  • Stripe-inspired UI design
  • Comprehensive documentation

Next Steps 📝​

  1. ✅ Set up environment variables
  2. ✅ Run database migration
  3. ✅ Test in sandbox environment
  4. ⬜ Request production credentials from Intuit
  5. ⬜ Complete UAT testing
  6. ⬜ Deploy to production
  7. ⬜ Monitor first transactions

Tips for Success​

💡 Start with sandbox - Always test thoroughly before going live
💡 Monitor closely - Watch first production transactions carefully
💡 Log everything - Keep detailed logs for debugging
💡 Test all methods - Try each payment method before launch
💡 Have support ready - Be prepared for user questions
💡 Check cart behavior - Verify persistence and clearing work correctly

Built with ❤️ using Intuit QuickBooks Embedded Payment SDK

Implementation Date: October 11, 2025
Status: ✅ Complete and Ready for Testing