Square

Every Square payment requires three pieces: an Application ID (identifies your app), an Access Token (authorizes the API call), and a Location ID (identifies the business location where the sale is made). In the Square Developer Console at developer.squareup.com, log in and create a new application or select an existing one. Navigate to the Credentials tab. You'll see two panels side by side: Sandbox and Production. Start with Sandbox. Copy the Sandbox Application ID (starts with 'sandbox-sq0idb-...') — this is safe to place in FlutterFlow as an App State constant. Copy the Sandbox Access Token (starts with 'EAAAl...' in sandbox) — this must go in your Cloud Function environment, NEVER in FlutterFlow. Keep it in a secure note for the next step. Now find your Location ID. In the Square Developer Console, click the Locations tab. Every Square account has at least one location; it represents a physical store or online presence. Copy the Location ID for your sandbox location (starts with 'L...'). Store this in FlutterFlow as a constant App Value (App Settings → App Values) — it's not a secret, just a configuration value. Jot down the sandbox base URL: https://connect.squareupsandbox.com/v2. The production base URL is https://connect.squareup.com/v2. Both return 401 UNAUTHORIZED if you mix tokens across environments — it's the single most common setup error.

Card tokenization is what turns a customer's raw card number into a safe, short-lived nonce that you can send to your server. The square_in_app_payments pub.dev package provides a native iOS and Android card entry UI managed entirely by Square — your code never sees the raw card data, which keeps you out of direct PCI DSS scope. In FlutterFlow, go to Custom Code in the left nav (code icon) → click '+ Add' → select 'Action'. Name it 'SquareCardTokenize'. In the Dependencies field, type 'square_in_app_payments' and accept the latest stable version (check pub.dev for the current version — it's in the 2.x range as of 2026). Add a second dependency: 'square_reader_sdk' is NOT needed; only 'square_in_app_payments' is required for in-app card entry. In the Return Value section, set the return type to String (the nonce). In the Arguments section, add one argument: `applicationId` (String). Paste the Dart code below into the code editor. The function initializes the Square SDK with your Application ID, calls the built-in card entry flow, and returns the nonce on success or throws an error on cancellation. Save the action. IMPORTANT: Custom Actions using native SDKs like this one do NOT work in FlutterFlow's web Run mode preview. You must test on a real device via the Companion app or a downloaded build. Web builds require a different approach (Custom Widget WebView with the Square Web Payments JavaScript SDK) — this action is for iOS/Android only.

1import 'package:square_in_app_payments/square_in_app_payments.dart';
2import 'package:square_in_app_payments/models.dart';
3
4Future<String> squareCardTokenize(String applicationId) async {
5  // Initialize the Square SDK with your Application ID
6  await SquareInAppPayments.setSquareApplicationId(applicationId);
7
8  // Completer to bridge the callback-based SDK to async/await
9  final completer = Completer<String>();
10
11  await SquareInAppPayments.startCardEntryFlow(
12    onCardNonceRequestSuccess: (CardDetails result) async {
13      // Close the card entry UI and return the nonce
14      await SquareInAppPayments.completeCardEntry(
15        onCardEntryComplete: () {
16          completer.complete(result.nonce);
17        },
18      );
19    },
20    onCardEntryCancel: () {
21      completer.completeError(Exception('User cancelled card entry'));
22    },
23  );
24
25  return completer.future;
26}

Your Cloud Function receives the nonce from FlutterFlow, attaches the Square access token and Idempotency-Key, and calls POST /v2/payments. The Idempotency-Key is critical: if the network drops after Square processes the charge but before your app receives the response, a retry without the key creates a double charge. Generate a UUID on the client (FlutterFlow custom function), pass it to the Cloud Function, and Square deduplicates the charge for up to 45 days. In the Firebase Console, go to Build → Functions → Get Started (follow the setup wizard if first time). In your terminal, navigate to your Firebase project's `functions/` directory and open `index.js`. Paste the code below. Set the environment variable before deploying: `firebase functions:config:set square.access_token='YOUR_SANDBOX_ACCESS_TOKEN' square.location_id='YOUR_SANDBOX_LOCATION_ID'`. Then run `firebase deploy --only functions:processSquarePayment`. After deployment, the Firebase Console shows your function URL: something like `https://us-central1-YOUR_PROJECT_ID.cloudfunctions.net/processSquarePayment`. Copy this URL — you'll paste it into the FlutterFlow API Call in the next step. For production, set the production access token and location ID via the same config command with your production values, and update the base URL in the function code to `https://connect.squareup.com/v2`.

1const functions = require('firebase-functions');
2const axios = require('axios');
3const { v4: uuidv4 } = require('uuid');
4
5exports.processSquarePayment = functions.https.onRequest(async (req, res) => {
6  // CORS for FlutterFlow web builds (not needed for mobile)
7  res.set('Access-Control-Allow-Origin', '*');
8  if (req.method === 'OPTIONS') {
9    res.set('Access-Control-Allow-Methods', 'POST');
10    res.set('Access-Control-Allow-Headers', 'Content-Type');
11    return res.status(204).send('');
12  }
13
14  const { nonce, amountMoney, idempotencyKey } = req.body;
15
16  if (!nonce || !amountMoney || !idempotencyKey) {
17    return res.status(400).json({ error: 'Missing required fields' });
18  }
19
20  const accessToken = functions.config().square.access_token;
21  const locationId = functions.config().square.location_id;
22  // Switch to https://connect.squareup.com/v2 for production
23  const baseUrl = 'https://connect.squareupsandbox.com/v2';
24
25  try {
26    const response = await axios.post(
27      `${baseUrl}/payments`,
28      {
29        source_id: nonce,
30        idempotency_key: idempotencyKey,
31        amount_money: amountMoney, // e.g. { amount: 1000, currency: 'USD' }
32        location_id: locationId,
33      },
34      {
35        headers: {
36          'Authorization': `Bearer ${accessToken}`,
37          'Content-Type': 'application/json',
38          'Square-Version': '2024-02-22',
39        },
40      }
41    );
42
43    return res.status(200).json({
44      status: response.data.payment.status,
45      paymentId: response.data.payment.id,
46    });
47  } catch (error) {
48    const errData = error.response?.data || { error: error.message };
49    return res.status(error.response?.status || 500).json(errData);
50  }
51});

Now connect FlutterFlow to the Cloud Function. In the left nav, click API Calls → + Add → Create API Group. Name the group 'SquarePayments'. Set the base URL to your Cloud Function URL (the full URL up to but NOT including the path, e.g. https://us-central1-YOUR_PROJECT_ID.cloudfunctions.net). Leave Authentication as 'None' — the authentication is handled inside the Cloud Function via Square's access token. Inside the group, click '+ Add API Call'. Name it 'ProcessPayment'. Set the Method to POST and the endpoint path to '/processSquarePayment'. In the Body tab, set the body type to JSON and add three variables: - `nonce` (String) — the card nonce from the Custom Action - `amountMoney` (Object) — JSON object with `amount` (integer, in cents) and `currency` (string, e.g. 'USD') - `idempotencyKey` (String) — a UUID generated by a Custom Function The body template should be: ``` { "nonce": "{{ nonce }}", "amountMoney": {{ amountMoney }}, "idempotencyKey": "{{ idempotencyKey }}" } ``` In the Response & Test tab, paste a sample success response from your Cloud Function (you can get one by calling it manually with a test nonce from the Square sandbox). Click 'Generate JSON Paths' — FlutterFlow creates path variables like `status` mapped to `$.status` and `paymentId` mapped to `$.paymentId`. These are the values you'll use in your Action Flow. Click Test — FlutterFlow sends a real request. If you get a 400 or 500, check that your Cloud Function is deployed and the URL is correct. A successful test returns `{ "status": "COMPLETED", "paymentId": "..." }`.

1{
2  "nonce": "{{ nonce }}",
3  "amountMoney": {{ amountMoney }},
4  "idempotencyKey": "{{ idempotencyKey }}"
5}

With all pieces ready — the Custom Action for tokenization and the API Call to the Cloud Function — connect them in your checkout button's Action Flow. Select your 'Pay' button → Actions panel → + Add Action. Step 1: Add a 'Custom Action' action and select SquareCardTokenize. Set the `applicationId` argument to your Sandbox Application ID constant from App Values. Set the output variable name, e.g. `cardNonce`, using the 'Define Output Variable' option. This action blocks until the user enters card details and taps 'Pay' in the Square card entry UI, then returns the nonce string. Step 2: After the Custom Action, add an 'Update App State' action to store the nonce in a page state variable (String) named `squareNonce`. This makes it available to the next action without chaining variable outputs directly (FlutterFlow handles chaining, but explicit state is clearer to debug). Step 3: Add a 'Backend/API Call' action. Select SquarePayments → ProcessPayment. Bind the variables: `nonce` → page state `squareNonce`, `idempotencyKey` → a UUID generated by a custom function (use Dart's `const Uuid().v4()` in a tiny custom function returning String), `amountMoney` → set as a static JSON string or bind to page state if the amount is user-defined. Step 4: After the API Call, add a Conditional action checking `response.status == 'COMPLETED'`. On TRUE: write to Firestore ('orders' collection with userId, paymentId, amount, status 'paid', createdAt) then navigate to confirmation. On FALSE: show a Snack Bar with 'Payment failed — please try a different card'. Test the entire flow on device with Square's sandbox test nonces or by running the card entry UI and entering a test card from Square's sandbox documentation.

Square's sandbox includes specific test card numbers that simulate different outcomes. Use these in the card entry UI opened by the Custom Action: - **Successful charge**: any Visa card number (e.g., 4111 1111 1111 1111), any future expiry, any CVV - **Declined card**: 4000 0000 0000 0002 - **Insufficient funds**: 4000 0000 0000 9995 Verify that each scenario triggers the correct FlutterFlow Action Flow branch. Check the Square Developer Console → Sandbox → Payments to see the test transactions listed. Also test the Idempotency-Key behavior: submit the same payment twice with the same key — Square should return the same paymentId (deduplication) rather than charging twice. Check the Developer Console; you should see one payment, not two. For production readiness: in the Firebase Cloud Function, change the `baseUrl` variable from `https://connect.squareupsandbox.com/v2` to `https://connect.squareup.com/v2`, and update the Firebase config to use your production access token and location ID. In FlutterFlow App Values, update the Application ID constant to your production Application ID. Run `firebase deploy --only functions:processSquarePayment` to redeploy with production settings. Important: Square also offers Webhooks (in the Square Dashboard → Webhooks) to receive server-side payment notifications for `payment.completed` and `payment.failed` events. Register a webhook pointing to a second Firebase Cloud Function to handle reconciliation and order status updates asynchronously — do not rely solely on the app-level API Call response for order fulfillment.