How to Integrate Square with V0

Log in to the Square Developer Dashboard at developer.squareup.com and either create a new application or select an existing one. You need three values: your Application ID (starts with sq0idp-), your Sandbox Access Token (starts with EAAAl or similar — found under Credentials tab → Sandbox), and your Location ID (found under Locations in the left sidebar — click the location to see its ID). Square provides completely separate sandbox and production credentials, which is excellent for testing. The sandbox is a full simulation of the Square API with test card numbers that trigger different responses. Save these three values securely — you will put them in Vercel environment variables, never in code. Next, install the Square Node.js SDK in your project. Open your project in your local editor or use V0's built-in GitHub integration to work with the code. In your project's package.json, you need to add the square package. The official package name is simply square and it is published by Square Inc on npm. Also note the Square Web Payments SDK script URL: https://sandbox.web.squarecdn.com/v1/square.js for sandbox and https://web.squarecdn.com/v1/square.js for production — you will load this via a script tag in your page to initialize the card payment form on the frontend.

1// Install the Square SDK
2// Run in your project terminal:
3// npm install square
4
5// package.json dependency (add to dependencies):
6// "square": "^40.0.0"

Open V0 and describe your checkout page in detail. Square's Web Payments SDK requires a div element with a specific ID (conventionally 'card-container') where it will inject the hosted card input fields. Ask V0 to create this container in the appropriate place in the form. The Square SDK injects an iframe into this container, so you cannot style the inner card fields directly — but you can style the container div and surrounding layout. Ask V0to create the order summary section alongside the payment form so users can see what they are paying for. V0 should generate a React component for the checkout page. After generating, you will add the Square SDK initialization logic to this component — V0 will not know the Square-specific JavaScript API calls, so you will need to add those manually or in a follow-up V0 prompt. The key pattern is: on component mount, load the Square Web Payments SDK script, call window.Square.payments(appId, locationId) to initialize, then call payments.card() to create a card payment instance, then card.attach('#card-container') to render the input fields into your div. When the user submits the form, call card.tokenize() to get the payment nonce, then send that nonce to your Next.js API route. Keep this flow in mind as you review V0's generated component code.

Create the server-side API route that processes Square payments using the Square Node.js SDK. This route receives a payment nonce (sourceId) from the frontend after the card is tokenized, along with the payment amount in cents. It creates a Square Payment using your access token and location ID, which are stored as server-only environment variables. The Square SDK uses the Client class from the square package to initialize a client with your access token and the environment (SANDBOX or PRODUCTION). The PaymentsApi on the client has a createPayment method that accepts the source ID, amount (in cents as a BigInt), currency, idempotency key, and location ID. The idempotency key is crucial — it prevents duplicate charges if the request is retried. Use a UUID or a combination of the nonce and timestamp. The route returns the payment ID on success so the frontend can display a confirmation. Always validate the request body on the server side before calling Square — check that the amount is a positive number and the nonce is a non-empty string. Return appropriate HTTP status codes so the frontend can handle errors gracefully.

1import { NextRequest, NextResponse } from 'next/server';
2import { Client, Environment } from 'square';
3
4const client = new Client({
5  accessToken: process.env.SQUARE_ACCESS_TOKEN,
6  environment:
7    process.env.SQUARE_ENVIRONMENT === 'production'
8      ? Environment.Production
9      : Environment.Sandbox,
10});
11
12export async function POST(request: NextRequest) {
13  try {
14    const body = await request.json();
15    const { sourceId, amountCents, currency = 'USD', note = '' } = body;
16
17    if (!sourceId || typeof sourceId !== 'string') {
18      return NextResponse.json(
19        { error: 'Invalid payment source' },
20        { status: 400 }
21      );
22    }
23
24    if (!amountCents || amountCents < 100) {
25      return NextResponse.json(
26        { error: 'Amount must be at least $1.00' },
27        { status: 400 }
28      );
29    }
30
31    const { result, statusCode } = await client.paymentsApi.createPayment({
32      sourceId,
33      idempotencyKey: crypto.randomUUID(),
34      amountMoney: {
35        amount: BigInt(amountCents),
36        currency,
37      },
38      locationId: process.env.SQUARE_LOCATION_ID,
39      note,
40    });
41
42    if (statusCode !== 200 || !result.payment) {
43      return NextResponse.json(
44        { error: 'Payment creation failed' },
45        { status: 500 }
46      );
47    }
48
49    return NextResponse.json({
50      paymentId: result.payment.id,
51      status: result.payment.status,
52      receiptUrl: result.payment.receiptUrl,
53    });
54  } catch (error: unknown) {
55    console.error('Square payment error:', error);
56    const message =
57      error instanceof Error ? error.message : 'Payment processing failed';
58    return NextResponse.json({ error: message }, { status: 500 });
59  }
60}

Now add the Square Web Payments SDK initialization to your checkout page component. The Square Web Payments SDK is loaded via a script tag and provides the window.Square global. You need to load this script before the component tries to initialize Square. In Next.js, use the next/script component with strategy='beforeInteractive' or load it via a useEffect. The initialization sequence is critical: first call Square.payments(applicationId, locationId) with your public-facing Application ID (this is safe to expose in the browser — it is not a secret key) and Location ID. Then call payments.card() to create a card payment form object. Then call card.attach('#card-container') to render the hosted card fields into your div. Wrap this in a useEffect that runs once on mount. The card.attach() call is asynchronous, so await it. In the payment submit handler, call card.tokenize() to get back a result object — if result.status is 'OK', extract result.token (the nonce/sourceId) and send it to your API route via fetch POST. The NEXT_PUBLIC_ prefix variables (Application ID and Location ID) are safe to use on the client side because they are public-facing identifiers, not secrets. Only the access token must stay server-side.

1'use client';
2
3import { useEffect, useRef, useState } from 'react';
4
5declare global {
6  interface Window {
7    Square: {
8      payments: (appId: string, locationId: string) => Promise<{
9        card: () => Promise<{
10          attach: (selector: string) => Promise<void>;
11          tokenize: () => Promise<{ status: string; token?: string; errors?: Array<{ message: string }> }>;
12        }>;
13      }>;
14    };
15  }
16}
17
18export default function CheckoutPage() {
19  const cardRef = useRef<Awaited<ReturnType<Awaited<ReturnType<typeof window.Square.payments>>['card']>> | null>(null);
20  const [loading, setLoading] = useState(false);
21  const [error, setError] = useState('');
22  const [success, setSuccess] = useState<{ paymentId: string; receiptUrl: string } | null>(null);
23
24  useEffect(() => {
25    const initSquare = async () => {
26      if (!window.Square) return;
27      try {
28        const payments = await window.Square.payments(
29          process.env.NEXT_PUBLIC_SQUARE_APP_ID!,
30          process.env.NEXT_PUBLIC_SQUARE_LOCATION_ID!
31        );
32        const card = await payments.card();
33        await card.attach('#card-container');
34        cardRef.current = card;
35      } catch (err) {
36        console.error('Square SDK init error:', err);
37        setError('Failed to load payment form. Please refresh.');
38      }
39    };
40
41    if (window.Square) {
42      initSquare();
43    } else {
44      const script = document.createElement('script');
45      script.src = 'https://sandbox.web.squarecdn.com/v1/square.js';
46      script.onload = initSquare;
47      document.head.appendChild(script);
48    }
49  }, []);
50
51  const handlePayment = async () => {
52    if (!cardRef.current) return;
53    setLoading(true);
54    setError('');
55
56    try {
57      const result = await cardRef.current.tokenize();
58
59      if (result.status !== 'OK' || !result.token) {
60        const msg = result.errors?.map((e) => e.message).join(', ') || 'Card tokenization failed';
61        setError(msg);
62        return;
63      }
64
65      const res = await fetch('/api/square/payment', {
66        method: 'POST',
67        headers: { 'Content-Type': 'application/json' },
68        body: JSON.stringify({ sourceId: result.token, amountCents: 2999 }),
69      });
70
71      const data = await res.json();
72
73      if (!res.ok) {
74        setError(data.error || 'Payment failed');
75        return;
76      }
77
78      setSuccess({ paymentId: data.paymentId, receiptUrl: data.receiptUrl });
79    } catch (err) {
80      setError('An unexpected error occurred. Please try again.');
81    } finally {
82      setLoading(false);
83    }
84  };
85
86  if (success) {
87    return (
88      <div className="max-w-md mx-auto p-8 text-center">
89        <h2 className="text-2xl font-bold text-green-600 mb-2">Payment Successful!</h2>
90        <p className="text-gray-600 mb-4">Order ID: {success.paymentId}</p>
91        {success.receiptUrl && (
92          <a href={success.receiptUrl} target="_blank" rel="noopener noreferrer"
93            className="text-blue-600 underline">View Receipt</a>
94        )}
95      </div>
96    );
97  }
98
99  return (
100    <div className="max-w-md mx-auto p-8">
101      <h1 className="text-2xl font-bold mb-6">Checkout</h1>
102      <div id="card-container" className="min-h-[89px] mb-4 border rounded-lg p-2" />
103      {error && <p className="text-red-600 text-sm mb-4">{error}</p>}
104      <button
105        onClick={handlePayment}
106        disabled={loading}
107        className="w-full bg-black text-white py-3 rounded-lg font-medium disabled:opacity-50"
108      >
109        {loading ? 'Processing...' : 'Pay Now'}
110      </button>
111    </div>
112  );
113}

Add all five Square environment variables to your Vercel project. Go to vercel.com, open your project, click Settings in the top navigation, and select Environment Variables from the left sidebar. Add the following variables: SQUARE_ACCESS_TOKEN set to your Sandbox Access Token (starts with EAAAl — server-only, no NEXT_PUBLIC_ prefix), SQUARE_LOCATION_ID set to your Location ID (server-only, no NEXT_PUBLIC_ prefix), SQUARE_ENVIRONMENT set to sandbox (server-only), NEXT_PUBLIC_SQUARE_APP_ID set to your Application ID (safe for client-side, uses NEXT_PUBLIC_ prefix), and NEXT_PUBLIC_SQUARE_LOCATION_ID set to your Location ID again (this one is public-facing and needed by the browser SDK). Yes, you need the Location ID in both a server-only and a public variable — the server route uses it via process.env.SQUARE_LOCATION_ID, and the browser SDK initialization needs it via process.env.NEXT_PUBLIC_SQUARE_LOCATION_ID. After adding all variables, redeploy your project from the Deployments tab. Test the integration using Square's sandbox test card numbers: 4111 1111 1111 1111 with any future expiry date, any 3-digit CVV, and any zip code. This test card always succeeds. For a declined payment test, use 4000 0000 0000 0002. Check your Square Developer Dashboard under Sandbox → Transactions to verify payments are being recorded.

1// Square test card numbers for sandbox testing:
2// Success: 4111 1111 1111 1111
3// Declined: 4000 0000 0000 0002
4// CVV Failure: 4000 0000 0000 0010
5// Expiry: any future date (MM/YY)
6// CVV: any 3 digits
7// Zip: any 5 digits