How to Integrate Lovable with Square

Go to developer.squareup.com and sign in with your Square account (or create a free account). In the top navigation, click 'Applications', then click 'Create Your First Application' or the '+' button. Give your application a name like 'My Lovable App' and click 'Save'. You'll land on the application detail page. In the left sidebar, click 'Credentials'. You'll see two sets of credentials: Sandbox (for development) and Production (for live payments). Start with Sandbox. Copy the Sandbox Access Token — it's a long string starting with EAAAlx... or similar. Also copy the Sandbox Application ID, which starts with 'sandbox-sq0idb-...'. Also note the Sandbox Location ID shown on the Credentials page — Square requires a location_id for creating payments and orders, representing which Square business location the transaction belongs to. Copy the Sandbox Location ID as well. Optionally, click 'Webhook Subscriptions' in the left sidebar and note this section — you'll return here in Step 4 to register your webhook endpoint URL. Square webhooks require an HTTPS URL, which your deployed Lovable project URL provides.

Open your Lovable project. Click the '+' button in the top-right area to open the panels, then select 'Cloud'. In the Cloud panel, expand the 'Secrets' section. You'll add three secrets for the Square integration. Add SQUARE_ACCESS_TOKEN with your Sandbox Access Token value. This is the credential your Edge Function will use to authenticate all Square API calls — it should never appear in any frontend code. Add SQUARE_LOCATION_ID with your Sandbox Location ID value. Square requires a location ID for payment and order operations to associate transactions with a specific business location. Add SQUARE_ENVIRONMENT with value 'sandbox' — the Square API has separate base URLs for sandbox (https://connect.squareupsandbox.com) and production (https://connect.squareup.com), and reading this from a secret lets you switch environments without code changes. For the frontend, you'll also need the Application ID — but this is a publishable identifier safe for client-side use (similar to Stripe's publishable key). Add it as VITE_SQUARE_APP_ID with your Sandbox Application ID value. The VITE_ prefix means Lovable includes it in the frontend build as an environment variable accessible via import.meta.env.VITE_SQUARE_APP_ID. Lovable's security system blocks approximately 1,200 hardcoded API keys daily from being committed to code. Using Cloud Secrets ensures your Square Access Token stays server-side and protected from accidental exposure.

Create the core backend function that processes Square payments. The payment flow works differently from Stripe's server-side charge: Square's Web Payments SDK runs in the browser, tokenizes the card details into a short-lived nonce (called a source_id), and sends that nonce to your Edge Function. The Edge Function then calls Square's Payments API with the nonce, amount, and location_id to create the actual charge. The Edge Function must handle the payment creation and return either a success response with the payment details or a structured error. Square returns detailed error codes when payments fail (for example, INSUFFICIENT_FUNDS, INVALID_CARD, EXPIRATION_FAILURE) that you can surface to users with helpful messages. For order management, Square has a two-step approach: you can create a lightweight payment directly (simpler, covered here), or create a full Order first and then attach the payment to it (more powerful for multi-item purchases with tax, discounts, and catalog integration). This tutorial implements the direct payment approach, which is suitable for single-product or fixed-amount checkouts.

1// supabase/functions/square-payment/index.ts
2import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
3
4const IS_SANDBOX = Deno.env.get("SQUARE_ENVIRONMENT") !== "production";
5const SQUARE_BASE = IS_SANDBOX
6  ? "https://connect.squareupsandbox.com"
7  : "https://connect.squareup.com";
8const ACCESS_TOKEN = Deno.env.get("SQUARE_ACCESS_TOKEN") ?? "";
9const LOCATION_ID = Deno.env.get("SQUARE_LOCATION_ID") ?? "";
10
11const corsHeaders = {
12  "Access-Control-Allow-Origin": "*",
13  "Access-Control-Allow-Methods": "POST, OPTIONS",
14  "Access-Control-Allow-Headers": "Content-Type, Authorization",
15};
16
17serve(async (req) => {
18  if (req.method === "OPTIONS") return new Response(null, { headers: corsHeaders });
19
20  try {
21    const { source_id, amount_cents, currency = "USD", idempotency_key } = await req.json();
22
23    const res = await fetch(`${SQUARE_BASE}/v2/payments`, {
24      method: "POST",
25      headers: {
26        Authorization: `Bearer ${ACCESS_TOKEN}`,
27        "Content-Type": "application/json",
28        "Square-Version": "2024-02-22",
29      },
30      body: JSON.stringify({
31        source_id,
32        idempotency_key,
33        amount_money: { amount: amount_cents, currency },
34        location_id: LOCATION_ID,
35      }),
36    });
37
38    const data = await res.json();
39    if (data.errors) {
40      return new Response(JSON.stringify({ errors: data.errors }), {
41        status: 400,
42        headers: { ...corsHeaders, "Content-Type": "application/json" },
43      });
44    }
45
46    const payment = data.payment;
47    return new Response(
48      JSON.stringify({ id: payment.id, status: payment.status, receipt_url: payment.receipt_url }),
49      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
50    );
51  } catch (err) {
52    return new Response(JSON.stringify({ error: err.message }), {
53      status: 500,
54      headers: { ...corsHeaders, "Content-Type": "application/json" },
55    });
56  }
57});

Square's Web Payments SDK renders a secure card input form inside an iframe hosted by Square. This keeps raw card numbers completely off your servers — the SDK tokenizes the card data client-side and gives you a short-lived nonce (source_id) to pass to your Edge Function. To use the SDK in a Lovable React component, you load the Square SDK script dynamically, initialize it with your Application ID and location ID, and call the SDK's card.tokenize() method when the customer submits the form. The tokenize call returns a source_id that you immediately send to your square-payment Edge Function. The frontend never sees the raw card number — only the nonce. Ask Lovable to create a SquarePaymentForm component. The component should load the SDK from the Square CDN, render the card container div that Square's SDK fills with its iframe, and handle the payment submission flow. Use a UUID library or crypto.randomUUID() to generate an idempotency_key before each payment attempt. For multi-item checkouts, build a cart data structure client-side and include the total amount as amount_cents in the Edge Function call. The Edge Function calculates and validates the total server-side before charging — never trust a client-supplied amount for the actual payment amount.

1// src/components/SquarePaymentForm.tsx
2import { useEffect, useRef, useState } from "react";
3import { Button } from "@/components/ui/button";
4import { supabase } from "@/integrations/supabase/client";
5
6declare global { interface Window { Square: any; } }
7
8interface SquarePaymentFormProps {
9  amountCents: number;
10  onSuccess?: (receiptUrl: string) => void;
11}
12
13export function SquarePaymentForm({ amountCents, onSuccess }: SquarePaymentFormProps) {
14  const cardRef = useRef<HTMLDivElement>(null);
15  const cardInstance = useRef<any>(null);
16  const [loading, setLoading] = useState(false);
17  const [error, setError] = useState("");
18
19  const appId = import.meta.env.VITE_SQUARE_APP_ID;
20  const locationId = import.meta.env.VITE_SQUARE_LOCATION_ID;
21  const isSandbox = import.meta.env.VITE_SQUARE_ENVIRONMENT !== "production";
22
23  useEffect(() => {
24    const script = document.createElement("script");
25    script.src = isSandbox
26      ? "https://sandbox.web.squarecdn.com/v1/square.js"
27      : "https://web.squarecdn.com/v1/square.js";
28    script.async = true;
29    script.onload = async () => {
30      const payments = window.Square.payments(appId, locationId);
31      const card = await payments.card();
32      if (cardRef.current) {
33        await card.attach(cardRef.current);
34        cardInstance.current = card;
35      }
36    };
37    document.head.appendChild(script);
38    return () => { document.head.removeChild(script); };
39  }, [appId, locationId, isSandbox]);
40
41  const handlePay = async () => {
42    if (!cardInstance.current) return;
43    setLoading(true);
44    setError("");
45    try {
46      const result = await cardInstance.current.tokenize();
47      if (result.status !== "OK") {
48        setError(result.errors?.map((e: any) => e.message).join(", ") ?? "Tokenization failed");
49        setLoading(false);
50        return;
51      }
52      const { data } = await supabase.functions.invoke("square-payment", {
53        body: { source_id: result.token, amount_cents: amountCents, idempotency_key: crypto.randomUUID() },
54      });
55      if (data?.errors) {
56        setError(data.errors.map((e: any) => e.detail).join(", "));
57      } else {
58        onSuccess?.(data.receipt_url);
59      }
60    } catch (e: any) {
61      setError(e.message);
62    }
63    setLoading(false);
64  };
65
66  return (
67    <div className="space-y-4">
68      <div ref={cardRef} className="min-h-[90px] border rounded-md p-2" />
69      {error && <p className="text-red-500 text-sm">{error}</p>}
70      <Button onClick={handlePay} disabled={loading} className="w-full">
71        {loading ? "Processing..." : `Pay $${(amountCents / 100).toFixed(2)}`}
72      </Button>
73    </div>
74  );
75}

Like all payment integrations, relying solely on the frontend success callback is not sufficient for production. Set up a Square webhook receiver Edge Function to independently confirm payment completion server-side. Create an Edge Function that listens for Square webhook events. Square sends a signature in the x-square-hmacsha256-signature header that you verify by computing an HMAC-SHA256 of the notification URL + request body using your webhook signature key. This verification is critical for preventing forged payment confirmations. After creating and deploying the Edge Function, register the webhook in the Square Developer Dashboard. In your application settings, click 'Webhook Subscriptions' → 'Add Subscription'. Enter your Edge Function URL (https://[project-id].supabase.co/functions/v1/square-webhook), give it a name, and select the events to subscribe to. For a basic payment flow, select 'payment.completed' and 'payment.failed'. Square will show you the Signature Key — copy this and save it as SQUARE_WEBHOOK_SIGNATURE_KEY in Cloud Secrets. For complex catalog sync workflows or multi-location businesses using Square's full inventory system, RapidDev's team can help architect a robust event-driven data pipeline that keeps your Lovable app's database in sync with Square in real time.

1// supabase/functions/square-webhook/index.ts
2import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
3import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
4
5serve(async (req) => {
6  const body = await req.text();
7  const signature = req.headers.get("x-square-hmacsha256-signature") ?? "";
8  const sigKey = Deno.env.get("SQUARE_WEBHOOK_SIGNATURE_KEY") ?? "";
9  const notificationUrl = Deno.env.get("SQUARE_WEBHOOK_URL") ?? "";
10
11  const payload = notificationUrl + body;
12  const key = await crypto.subtle.importKey(
13    "raw",
14    new TextEncoder().encode(sigKey),
15    { name: "HMAC", hash: "SHA-256" },
16    false,
17    ["sign"]
18  );
19  const signed = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
20  const expectedSig = btoa(String.fromCharCode(...new Uint8Array(signed)));
21
22  if (expectedSig !== signature) {
23    return new Response("Invalid signature", { status: 400 });
24  }
25
26  const event = JSON.parse(body);
27  if (event.type === "payment.completed") {
28    const supabase = createClient(
29      Deno.env.get("SUPABASE_URL") ?? "",
30      Deno.env.get("SUPABASE_SERVICE_ROLE_KEY") ?? ""
31    );
32    const paymentId = event.data?.object?.payment?.id;
33    if (paymentId) {
34      await supabase.from("orders").update({ status: "paid" }).eq("square_payment_id", paymentId);
35    }
36  }
37
38  return new Response("OK", { status: 200 });
39});