Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Square to Fondoo

Live4 min readUpdated

If you take payments with Square, online or in person, this connection lets Fondoo see your completed payments, refunds and subscriptions. Your AI agent can include Square sales in your revenue reports, credit online sales to the visits that led to them, and keep subscribers' plans in sync. Fondoo only reads. It cannot charge, refund or cancel.

What Fondoo can do with it

Six read-only actions, used through connector_action:

  • transactions.pull: completed payments and their refunds.
  • subscriptions.pull: Square subscription status (active, past due, cancelled).
  • customers.list: customer IDs and emails.
  • webhooks.verify and webhooks.parse: check and read Square webhook notifications.
  • dashboard.link: a link into the Square Dashboard for a person to open.

After you bind the connection with connect_revenue_source, Fondoo imports payments as orders and analytics conversions. Subscriptions become entitlements that can update a customer's plan in your app.

What needs your approval: an agent binding a live source or changing its product map needs the owner's approval. Reads never do. Refunds stay in Square.

Before you start

  • A Square seller account, and a free developer account at developer.squareup.com using the same login.
  • Sandbox or production. The Sandbox token only sees Sandbox test data. Use the Production token for real sales.
  • Live mode in Fondoo needs a paid Fondoo plan. Test mode works on any plan.
  • Locations. Fondoo reads payments for your main location unless you pass a locationId when pulling.

Step by step: get your credentials

This guide uses the personal access token for your own Square account.

  1. Sign in to the Developer Console.
  2. Open your application, or create one (any name, for example Fondoo).
  3. In the left pane, click Credentials.
  4. At the top, choose Production (or Sandbox for testing).
  5. In the Production Access token box, click Show and copy the token (access tokens).

The personal access token gives unrestricted access to your own Square account, and it can't be limited. Fondoo only ever reads with it, but keep it as safe as a password. If you build your own Square OAuth app instead, a token limited to PAYMENTS_READ, ORDERS_READ, SUBSCRIPTIONS_READ, CUSTOMERS_READ and MERCHANT_PROFILE_READ is enough (permissions).

What goes where:

Fondoo fieldWhat to paste
Square access token (accessToken)the token from step 5
Environment (production or sandbox) (environment)sandbox for a Sandbox token. Leave empty for production
Webhook signature key (webhookSecret)leave empty for now. Add it in the Webhooks step

Connect it in Fondoo

In the dashboard

  1. Open Connections.
  2. Under Available, find Square (in Payments) and click Use a key.
  3. Click Open secure key entry (single use, expires after 15 minutes). Paste the token and environment, then save.
  4. Click Check connection on the new card.

By asking your agent

Example prompt:

Connect my Square account to my site and import my sales. Send me a secure link for the token.

The agent runs:

add_connection_key({ provider: "square", siteId: "<site id>" })
test_connection({ connectionId: "<id>" })
connect_revenue_source({ siteId: "<site id>", connectionId: "<id>", mode: "live",
  productMap: { "<subscription plan variation ID>": "pro" } })   // returns webhookUrl
sync_revenue_source({ sourceId: "<source id>" })

For a help link only: connect_service({provider:"square", siteId}) (signed, valid for 15 minutes).

Over REST: POST https://api.getfondoo.com/v1/ops/<operation> with Authorization: Bearer <your Fondoo API key> and the same JSON, for example POST /v1/ops/add_connection_key with {"provider":"square","siteId":"<site id>"}.

Webhooks

  1. Copy the webhookUrl from connect_revenue_source (or get_revenue_sources). It looks like https://<Fondoo API host>/webhooks/revenue/<connectionId>.
  2. In the Developer Console, open your app and go to Webhooks → Subscriptions → Add subscription (subscribe).
  3. Enter a name and paste the URL as the notification URL. Make sure it matches exactly, with no extra slash, because Square signs the URL itself.
  4. Select an API version and these events: payment.created, payment.updated, refund.created, refund.updated, subscription.created, subscription.updated.
  5. Click Save.
  6. Click the endpoint name. Under Endpoint Details, find the Signature Key box and click Show. Copy the key.
  7. In Fondoo run rotate_connection_key({connectionId}). On the secure page, paste the access token and environment again, plus the signature key. The page replaces all fields together.

Square signs each notification with the x-square-hmacsha256-signature header, an HMAC-SHA256 made from the signature key, the notification URL and the raw body (validate notifications). Fondoo checks it before recording anything.

Attribution: Square has no checkout field that is copied onto the payment for this purpose. Fondoo reads the payment's reference_id: either a bare visit UUID, or visit_id=<uuid>;external_user_id=<id> (40 characters max). If that is empty, it reads the same format from the payment note. Square doesn't document this use, so it may differ for your account.

Test that it works

  1. Run test_connection. It reads your merchant profile. Payments, refunds, subscriptions and customers show as "unknown" until Fondoo first reads them. That's normal.
  2. Run sync_revenue_source({sourceId}) and check get_revenue_sources({siteId}) for lastSyncAt and no lastError.
  3. Make a Sandbox payment (with a Sandbox token and Sandbox webhook). Check that the payment appears in Fondoo after the next webhook or sync.

Troubleshooting

  • 401 UNAUTHORIZED. The token is wrong, or it's a Sandbox token used as production (or the reverse). Set Environment to match.
  • No payments from some locations. Fondoo reads the main location by default. Pass locationId to transactions.pull for other locations.
  • Webhook signature fails. The notification URL in Square must match Fondoo's URL exactly, including https:// and the connection ID. Copy the signature key again from Endpoint Details.
  • 403 on subscriptions or customers. This happens with a limited OAuth token. Add SUBSCRIPTIONS_READ or CUSTOMERS_READ.
  • "This site and mode already has a source for this provider". One Square source per site and mode. Find it with get_revenue_sources.
  • 429 RATE_LIMITED. Square doesn't publish fixed limits (handling errors). Fondoo keeps to 60 requests per minute and backs off.

Limits, data and security

  • What Fondoo stores: the access token and signature key, encrypted, never shown again. From Square it keeps payment and refund amounts, subscription status, and customer IDs and emails.
  • Rotate: Square's docs don't describe rotating the personal access token itself. To cut off access, revoke or replace it in the Developer Console (team members need permission to manage production credentials). Then run rotate_connection_key({connectionId}) with the new token.
  • Disconnect: disconnect_revenue_source({sourceId}) stops the feed (imported data stays). delete_connection({connectionId}) removes the stored token. Then delete the webhook subscription in Square.
  • Dashboard links use observed Square URL patterns that Square doesn't document, so they may open a general page.