@bailierich/booking-components 2.0.0

package/docs/PAYMENT_INTEGRATION.md

@@ -0,0 +1,766 @@
+# Payment Integration Guide
+
+Complete guide for integrating payment providers with the booking components.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Square Integration](#square-integration)
+- [Stripe Integration](#stripe-integration)
+- [Deposit vs Full Payment](#deposit-vs-full-payment)
+- [Handling Payment Errors](#handling-payment-errors)
+- [Security Best Practices](#security-best-practices)
+
+---
+
+## Overview
+
+The Confirmation component supports payment collection during the booking process. You can integrate Square, Stripe, or any other payment provider.
+
+### Payment Flow
+
+1. User completes booking details (service, date, time, contact info)
+2. User reaches confirmation step
+3. Payment form is presented (deposit or full payment)
+4. Payment is processed
+5. Booking is confirmed and saved
+6. Confirmation email is sent
+
+---
+
+## Square Integration
+
+### 1. Install Square SDK
+
+```bash
+npm install square
+```
+
+### 2. Set Up Square Web Payments SDK
+
+```tsx
+// lib/square.ts
+export async function initializeSquarePayments() {
+  if (!window.Square) {
+    throw new Error('Square.js failed to load');
+  }
+
+  const payments = window.Square.payments(
+    process.env.NEXT_PUBLIC_SQUARE_APPLICATION_ID!,
+    process.env.NEXT_PUBLIC_SQUARE_LOCATION_ID!
+  );
+
+  return payments;
+}
+
+export async function createSquareCard(payments: any) {
+  const card = await payments.card();
+  await card.attach('#square-card-container');
+  return card;
+}
+```
+
+### 3. Create Payment Component
+
+```tsx
+// components/SquarePayment.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { initializeSquarePayments, createSquareCard } from '@/lib/square';
+
+interface SquarePaymentProps {
+  amount: number;
+  onPaymentSuccess: (paymentId: string) => void;
+  onPaymentError: (error: Error) => void;
+}
+
+export function SquarePayment({
+  amount,
+  onPaymentSuccess,
+  onPaymentError
+}: SquarePaymentProps) {
+  const [card, setCard] = useState<any>(null);
+  const [isProcessing, setIsProcessing] = useState(false);
+
+  useEffect(() => {
+    async function setupSquare() {
+      try {
+        const payments = await initializeSquarePayments();
+        const squareCard = await createSquareCard(payments);
+        setCard(squareCard);
+      } catch (error) {
+        console.error('Failed to initialize Square:', error);
+        onPaymentError(new Error('Payment system initialization failed'));
+      }
+    }
+
+    setupSquare();
+
+    return () => {
+      if (card) {
+        card.destroy();
+      }
+    };
+  }, []);
+
+  const handlePayment = async () => {
+    if (!card || isProcessing) return;
+
+    setIsProcessing(true);
+
+    try {
+      // Tokenize card
+      const result = await card.tokenize();
+
+      if (result.status === 'OK') {
+        // Send token to backend
+        const response = await fetch('/api/payments/square', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            sourceId: result.token,
+            amount: amount * 100, // Convert to cents
+            currency: 'USD'
+          })
+        });
+
+        if (!response.ok) {
+          throw new Error('Payment processing failed');
+        }
+
+        const data = await response.json();
+        onPaymentSuccess(data.paymentId);
+      } else {
+        throw new Error(result.errors[0]?.message || 'Tokenization failed');
+      }
+    } catch (error) {
+      onPaymentError(error as Error);
+    } finally {
+      setIsProcessing(false);
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div id="square-card-container" className="min-h-[200px]" />
+
+      <button
+        onClick={handlePayment}
+        disabled={!card || isProcessing}
+        className="w-full py-3 px-6 rounded-lg text-white font-medium disabled:opacity-50"
+        style={{ backgroundColor: '#006AFF' }}
+      >
+        {isProcessing ? 'Processing...' : `Pay $${amount.toFixed(2)}`}
+      </button>
+    </div>
+  );
+}
+```
+
+### 4. Backend API Route
+
+```tsx
+// app/api/payments/square/route.ts
+import { Client, Environment } from 'square';
+
+const client = new Client({
+  accessToken: process.env.SQUARE_ACCESS_TOKEN!,
+  environment: Environment.Production
+});
+
+export async function POST(request: Request) {
+  try {
+    const { sourceId, amount, currency } = await request.json();
+
+    const { result } = await client.paymentsApi.createPayment({
+      sourceId,
+      amountMoney: {
+        amount: BigInt(amount),
+        currency
+      },
+      locationId: process.env.SQUARE_LOCATION_ID!,
+      idempotencyKey: crypto.randomUUID()
+    });
+
+    return Response.json({
+      paymentId: result.payment?.id,
+      status: result.payment?.status
+    });
+  } catch (error) {
+    console.error('Square payment error:', error);
+    return Response.json(
+      { error: 'Payment failed' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### 5. Use with Confirmation Component
+
+```tsx
+import { Confirmation } from '@oviah/booking-components';
+import { SquarePayment } from '@/components/SquarePayment';
+
+<Confirmation
+  service={selectedService}
+  addons={selectedAddons}
+  selectedDate={selectedDate}
+  selectedTime={selectedTime}
+  contactInfo={contactInfo}
+  paymentProvider="square"
+  paymentConfig={{
+    depositPercentage: 20
+  }}
+  onConfirm={async () => {
+    // Payment handled by SquarePayment component
+  }}
+  colors={colors}
+/>
+```
+
+---
+
+## Stripe Integration
+
+### 1. Install Stripe SDK
+
+```bash
+npm install @stripe/stripe-js @stripe/react-stripe-js
+```
+
+### 2. Set Up Stripe Elements
+
+```tsx
+// lib/stripe.ts
+import { loadStripe } from '@stripe/stripe-js';
+
+export const stripePromise = loadStripe(
+  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
+);
+```
+
+### 3. Create Payment Component
+
+```tsx
+// components/StripePayment.tsx
+'use client';
+
+import { useState } from 'react';
+import { Elements, CardElement, useStripe, useElements } from '@stripe/react-stripe-js';
+import { stripePromise } from '@/lib/stripe';
+
+interface StripePaymentFormProps {
+  amount: number;
+  onPaymentSuccess: (paymentIntentId: string) => void;
+  onPaymentError: (error: Error) => void;
+}
+
+function StripePaymentForm({
+  amount,
+  onPaymentSuccess,
+  onPaymentError
+}: StripePaymentFormProps) {
+  const stripe = useStripe();
+  const elements = useElements();
+  const [isProcessing, setIsProcessing] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!stripe || !elements) return;
+
+    setIsProcessing(true);
+
+    try {
+      // Create payment intent on backend
+      const response = await fetch('/api/payments/stripe/create-intent', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ amount: amount * 100 }) // Convert to cents
+      });
+
+      const { clientSecret } = await response.json();
+
+      // Confirm payment
+      const cardElement = elements.getElement(CardElement);
+      if (!cardElement) throw new Error('Card element not found');
+
+      const result = await stripe.confirmCardPayment(clientSecret, {
+        payment_method: {
+          card: cardElement
+        }
+      });
+
+      if (result.error) {
+        throw new Error(result.error.message);
+      }
+
+      onPaymentSuccess(result.paymentIntent.id);
+    } catch (error) {
+      onPaymentError(error as Error);
+    } finally {
+      setIsProcessing(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <div className="p-4 border border-gray-200 rounded-lg">
+        <CardElement
+          options={{
+            style: {
+              base: {
+                fontSize: '16px',
+                color: '#424770',
+                '::placeholder': {
+                  color: '#aab7c4'
+                }
+              },
+              invalid: {
+                color: '#9e2146'
+              }
+            }
+          }}
+        />
+      </div>
+
+      <button
+        type="submit"
+        disabled={!stripe || isProcessing}
+        className="w-full py-3 px-6 rounded-lg text-white font-medium disabled:opacity-50"
+        style={{ backgroundColor: '#635BFF' }}
+      >
+        {isProcessing ? 'Processing...' : `Pay $${amount.toFixed(2)}`}
+      </button>
+    </form>
+  );
+}
+
+export function StripePayment(props: StripePaymentFormProps) {
+  return (
+    <Elements stripe={stripePromise}>
+      <StripePaymentForm {...props} />
+    </Elements>
+  );
+}
+```
+
+### 4. Backend API Routes
+
+```tsx
+// app/api/payments/stripe/create-intent/route.ts
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2023-10-16'
+});
+
+export async function POST(request: Request) {
+  try {
+    const { amount } = await request.json();
+
+    const paymentIntent = await stripe.paymentIntents.create({
+      amount,
+      currency: 'usd',
+      automatic_payment_methods: {
+        enabled: true
+      }
+    });
+
+    return Response.json({
+      clientSecret: paymentIntent.client_secret
+    });
+  } catch (error) {
+    console.error('Stripe payment intent error:', error);
+    return Response.json(
+      { error: 'Failed to create payment intent' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+---
+
+## Deposit vs Full Payment
+
+### Configuration
+
+```tsx
+const paymentConfig = {
+  depositPercentage: 20,  // 20% deposit
+  requireDeposit: true    // or false for full payment
+};
+
+<Confirmation
+  paymentConfig={paymentConfig}
+  // ... other props
+/>
+```
+
+### Calculating Amounts
+
+```tsx
+function calculatePaymentAmounts(
+  servicePrice: number,
+  addonsPrice: number,
+  depositPercentage: number
+) {
+  const total = servicePrice + addonsPrice;
+  const deposit = depositPercentage > 0
+    ? (total * depositPercentage) / 100
+    : total;
+  const remaining = total - deposit;
+
+  return {
+    total: total.toFixed(2),
+    deposit: deposit.toFixed(2),
+    remaining: remaining.toFixed(2)
+  };
+}
+
+// Usage
+const amounts = calculatePaymentAmounts(100, 25, 20);
+// {
+//   total: "125.00",
+//   deposit: "25.00",
+//   remaining: "100.00"
+// }
+```
+
+### Handling Remaining Balance
+
+```tsx
+// Store deposit payment info
+await prisma.booking.create({
+  data: {
+    serviceId: selectedService,
+    date: selectedDate,
+    time: selectedTime,
+    totalAmount: amounts.total,
+    depositAmount: amounts.deposit,
+    depositPaid: true,
+    depositPaymentId: paymentId,
+    remainingBalance: amounts.remaining,
+    balanceDueDate: appointmentDate // Due at appointment
+  }
+});
+
+// Send confirmation with balance due info
+await sendConfirmationEmail({
+  to: contactInfo.email,
+  booking: bookingData,
+  depositAmount: amounts.deposit,
+  remainingBalance: amounts.remaining,
+  balanceDueText: `$${amounts.remaining} due at your appointment`
+});
+```
+
+---
+
+## Handling Payment Errors
+
+### Error Types
+
+```typescript
+enum PaymentErrorType {
+  CARD_DECLINED = 'card_declined',
+  INSUFFICIENT_FUNDS = 'insufficient_funds',
+  INVALID_CARD = 'invalid_card',
+  PROCESSING_ERROR = 'processing_error',
+  NETWORK_ERROR = 'network_error'
+}
+
+interface PaymentError {
+  type: PaymentErrorType;
+  message: string;
+  code?: string;
+}
+```
+
+### Error Handling Implementation
+
+```tsx
+function handlePaymentError(error: Error) {
+  let userMessage = 'Payment failed. Please try again.';
+
+  // Parse error message
+  if (error.message.includes('declined')) {
+    userMessage = 'Your card was declined. Please use a different payment method.';
+  } else if (error.message.includes('insufficient')) {
+    userMessage = 'Insufficient funds. Please use a different card.';
+  } else if (error.message.includes('invalid')) {
+    userMessage = 'Invalid card information. Please check and try again.';
+  } else if (error.message.includes('network')) {
+    userMessage = 'Network error. Please check your connection and try again.';
+  }
+
+  // Log error for debugging
+  console.error('Payment error:', error);
+
+  // Track error analytics
+  analytics.track('Payment Error', {
+    error: error.message,
+    timestamp: new Date().toISOString()
+  });
+
+  // Show user-friendly message
+  toast.error(userMessage);
+
+  // Optional: Send to error tracking service
+  if (typeof window !== 'undefined' && window.Sentry) {
+    window.Sentry.captureException(error, {
+      tags: { context: 'payment' }
+    });
+  }
+}
+```
+
+### Retry Logic
+
+```tsx
+async function processPaymentWithRetry(
+  paymentFn: () => Promise<string>,
+  maxRetries = 3
+): Promise<string> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await paymentFn();
+    } catch (error) {
+      lastError = error as Error;
+
+      // Don't retry for card declined or invalid card
+      if (
+        error.message.includes('declined') ||
+        error.message.includes('invalid')
+      ) {
+        throw error;
+      }
+
+      // Wait before retrying (exponential backoff)
+      if (attempt < maxRetries) {
+        await new Promise(resolve =>
+          setTimeout(resolve, Math.pow(2, attempt) * 1000)
+        );
+      }
+    }
+  }
+
+  throw lastError || new Error('Payment failed after retries');
+}
+```
+
+---
+
+## Security Best Practices
+
+### 1. Never Store Card Details
+
+```tsx
+// ❌ BAD - Never do this
+const cardInfo = {
+  number: '4242424242424242',
+  cvv: '123',
+  expiry: '12/25'
+};
+localStorage.setItem('card', JSON.stringify(cardInfo));
+
+// ✅ GOOD - Use payment provider tokens
+const { token } = await stripe.createToken(cardElement);
+// Only store/send the token, never raw card data
+```
+
+### 2. Use HTTPS Only
+
+```tsx
+// next.config.js
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: [
+          {
+            key: 'Strict-Transport-Security',
+            value: 'max-age=31536000; includeSubDomains'
+          }
+        ]
+      }
+    ];
+  }
+};
+```
+
+### 3. Validate on Backend
+
+```tsx
+// app/api/payments/route.ts
+export async function POST(request: Request) {
+  const { amount, sourceId } = await request.json();
+
+  // Validate amount
+  if (!amount || amount < 50) {
+    return Response.json(
+      { error: 'Invalid amount' },
+      { status: 400 }
+    );
+  }
+
+  // Validate source
+  if (!sourceId || typeof sourceId !== 'string') {
+    return Response.json(
+      { error: 'Invalid payment source' },
+      { status: 400 }
+    );
+  }
+
+  // Process payment...
+}
+```
+
+### 4. Use Idempotency Keys
+
+```tsx
+// Prevent duplicate charges
+const idempotencyKey = `booking-${bookingId}-${Date.now()}`;
+
+await stripe.paymentIntents.create({
+  amount,
+  currency: 'usd',
+  // ... other params
+}, {
+  idempotencyKey
+});
+```
+
+### 5. Implement Rate Limiting
+
+```tsx
+// middleware.ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(5, '1 m') // 5 requests per minute
+});
+
+export async function middleware(request: Request) {
+  if (request.url.includes('/api/payments')) {
+    const ip = request.headers.get('x-forwarded-for') ?? 'unknown';
+    const { success } = await ratelimit.limit(ip);
+
+    if (!success) {
+      return new Response('Too many requests', { status: 429 });
+    }
+  }
+
+  return NextResponse.next();
+}
+```
+
+---
+
+## Complete Integration Example
+
+```tsx
+// app/booking/page.tsx
+'use client';
+
+import { useState } from 'react';
+import { BookingFlow } from '@oviah/booking-components';
+import { SquarePayment } from '@/components/SquarePayment';
+import { toast } from 'sonner';
+
+export default function BookingPage() {
+  const [bookingData, setBookingData] = useState(null);
+
+  const handleBookingComplete = async (data: any) => {
+    try {
+      // 1. Create booking (pending payment)
+      const bookingResponse = await fetch('/api/bookings', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          ...data,
+          status: 'pending_payment'
+        })
+      });
+
+      const booking = await bookingResponse.json();
+      setBookingData(booking);
+
+      // 2. Show payment UI
+      // Payment handled by embedded component
+
+    } catch (error) {
+      toast.error('Failed to create booking');
+      console.error(error);
+    }
+  };
+
+  const handlePaymentSuccess = async (paymentId: string) => {
+    try {
+      // Update booking with payment info
+      await fetch(`/api/bookings/${bookingData.id}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          status: 'confirmed',
+          paymentId
+        })
+      });
+
+      // Send confirmation email
+      await fetch('/api/emails/confirmation', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ bookingId: bookingData.id })
+      });
+
+      // Redirect to success page
+      window.location.href = `/booking/success?id=${bookingData.id}`;
+
+    } catch (error) {
+      toast.error('Failed to confirm booking');
+      console.error(error);
+    }
+  };
+
+  const handlePaymentError = (error: Error) => {
+    toast.error('Payment failed. Please try again.');
+    console.error(error);
+  };
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <BookingFlow
+        config={config}
+        colors={colors}
+        services={services}
+        onComplete={handleBookingComplete}
+      />
+
+      {bookingData && (
+        <SquarePayment
+          amount={bookingData.depositAmount}
+          onPaymentSuccess={handlePaymentSuccess}
+          onPaymentError={handlePaymentError}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## See Also
+
+- [CALLBACKS.md](./CALLBACKS.md) - Event handling patterns
+- [DATA_SHAPES.md](./DATA_SHAPES.md) - Data structures
+- [API.md](./API.md) - Component reference