{"title":"Square","slug":"square-payment-provider","url":"https://support.storeconnect.com/articles/square-payment-provider","url_markdown":"https://support.storeconnect.com/articles/square-payment-provider.md","subtitle":null,"summary":"Configure Square for online and POS payments in StoreConnect, including subscriptions, Google Pay, Apple Pay, 3DS, and multi-location device pairing.","type":"Help_Documentation","video_url":"","keywords":"square, square payment provider, payment integration, pos payments, online payments, subscriptions, apple pay, google pay, 3d secure, 3ds, point of sale, device pairing, multi-location, square credentials, sandbox, access token, location id, store variable, square pos","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"Square is a third party payment provider. If you use Square, you can integrate it directly with StoreConnect. Square works for:\n\n-   Standard checkout transactions\n-   Subscription payments\n-   Apple Pay and Google Pay transactions\n-   Pre-authorization\n-   Enforcing additional security with [3D Secure (3DS)](https://squareup.com/help/au/en/article/7623-risk-manager-3d-secure-3ds) and [Enterprise-grade Encryption](https://squareup.com/help/us/en/article/3797-secure-data-encryption)\n-   In-person card payments on [Square Terminal](https://squareup.com/us/en/campaigns/switch-to-terminal) devices, paired to a StoreConnect register\n\n:::tip\n\nAlready have your credentials? Go to\n[Configure Square in StoreConnect](#configure-square-in-storeconnect).\n\n:::\n\n## What you need\n\n1.  A Square developer account.\n2.  Square credentials and location IDs.\n3.  A sandbox environment (recommended).\n4.  Outlets set up in StoreConnect (POS only).\n5.  Minimal code and admin know-how.\n\n:::warning\nA physical Square Terminal cannot pair using sandbox credentials. Use the\nproduction Application ID and Access Token from Square's **Credentials** page for\n**API Key** and **API Secret**. See Square's\n[Sandbox overview](https://developer.squareup.com/docs/devtools/sandbox/overview)\nand **Testing in sandbox** below. Sandbox is fine for testing the online\nstorefront.\n\n**API Mode** does control which Square environment online payments use, so set\nit to `production` for a live store. Terminal pairing always runs against Square\nproduction, so pairing succeeds or fails on the credentials themselves, not on\nthis field.\n:::\n\n## Get Square credentials\n\n1.  If you haven't got a Square developer account, [create one and add an application](https://developer.squareup.com/docs/get-started/create-account-and-application).\n2.  Create a new application just for StoreConnect. Each Square app comes with [access credentials](https://developer.squareup.com/docs/build-basics/access-tokens) for use in a Sandbox or Production environment.\n\n    :::tip\n    Set up a sandbox first to test it works how you want, then update to the production\n    credentials later.\n    :::\n\n3.  In Square, go to the **Credentials** page of your app.\n\n    ![Square Credentials page showing the Application ID and Access Token fields](https://res.cloudinary.com/hzkr6fi81/image/upload/v1765767620/knowledge/payment-providers/Square-Credentials_sxwl54.png)\n\n4.  Copy the **Application ID** and **Access Token**.\n5.  Go to the **Locations** section and copy the **Location ID**.\n\n    ![Square Locations section with the Location ID for a location](https://res.cloudinary.com/hzkr6fi81/image/upload/v1765767620/knowledge/payment-providers/Square-Locations_azge8u.png)\n\n:::note\nSandbox and production are separate Square environments: credentials, Location\nIDs, and other resources from one **cannot** be used with the other. If you\nswitch API Mode from sandbox to production later, you need a fresh Application\nID, Access Token, and Location ID from the production app, not just a mode\ntoggle.\n:::\n\n## Testing in sandbox\n\nSquare's Sandbox is a free, isolated environment for testing without moving real\nmoney. See Square's own\n[Sandbox overview](https://developer.squareup.com/docs/devtools/sandbox/overview)\nand [Sandbox payments](https://developer.squareup.com/docs/devtools/sandbox/payments)\ndocs for the full reference. A few things that matter for a StoreConnect setup:\n\n-   **Card-not-present (online storefront) testing is supported.** Use Square's\n    test card numbers to trigger predictable outcomes at checkout:\n\n    | Card | Number | CVV | Result |\n    |---|---|---|---|\n    | Visa | `4111 1111 1111 1111` | `111` | Approved (any future expiry) |\n    | Mastercard | `5105 1051 0510 5100` | `111` | Approved (any future expiry) |\n    | Visa | `4000 0000 0000 0002` | `111` | Declined |\n\n    Postal code `99999` and expiry `01/40` simulate a postal-code or\n    expiration-date error respectively.\n\n-   **Card-present (POS terminal) testing is not supported at all**, in any\n    form. Square's own docs are explicit: \"Square hardware, such as a POS\n    terminal, cannot be used in the Sandbox,\" and \"Testing card-present\n    scenarios is currently not supported.\" This is the same limitation behind\n    the production-credentials requirement for pairing a physical terminal; see\n    the warning under **What you need**.\n\n## Configure Square in StoreConnect\n\n1.  Open StoreConnect and go to **Settings \u003e Payments \u003e Payment providers**.\n2.  Select **New**. Complete the fields as follows, then **Save**:\n\n| StoreConnect field | Square data |\n|---|---|\n| **Name** | Square. For a test provider, add `- Test`. |\n| **Provider** | Select Square from the list. |\n| **API Mode** | Enter `sandbox` or `production`. |\n| **API Key** | The **Application ID** from your Square account. |\n| **API Secret** | The **Access Token** from your Square account. |\n| **API Options** | See **API Options format** below. |\n\n### API Options format\n\n1.  Enter the options as YAML key/value pairs, one option per line. JSON is\n    valid YAML, so a braced object parses the same way:\n\n    ```yaml\n    show_wallets: true\n    location_id: YOUR_LOCATION_ID\n    ```\n\n2.  For an option that holds a set of values, such as `pos_outlets`, write the\n    nested keys on one line inside `{ }`:\n\n    ```yaml\n    show_wallets: true\n    location_id: YOUR_LOCATION_ID\n    pos_outlets: { a24ao000001lE6zAAE: L003B9TTM5NC5, default: L003B9TTM5NC5 }\n    ```\n\n    All options live in one **API Options** value. Add new options to what is\n    already there rather than replacing it.\n\n3.  Add only the options you need:\n\n    | Option | Purpose |\n    |--------|---------|\n    | `location_id` | The Square Location ID for online payments. POS ignores this and takes its location from `pos_outlets`. |\n    | `show_wallets` | Set `true` to show Apple Pay and Google Pay at checkout. |\n    | `pos_outlets` | Maps each StoreConnect outlet to a Square Location ID for POS (see below). |\n\n    A web-only store needs `location_id`. A POS-only store needs `pos_outlets`.\n    A store that takes both needs both.\n\n:::warning\nDo not split a nested option across indented lines. This form looks correct and\nfails:\n\n```yaml\n\npos_outlets:\n  a24ao000001lE6zAAE: L003B9TTM5NC5\n  default: L003B9TTM5NC5\n```\n\nLine breaks that follow a key are normalized before the field is parsed, which\ncan collapse the indented block into a single invalid line. The whole field then\nresolves to empty: no error appears on the record, and POS calls that need\n`pos_outlets` (including terminal pairing) return a 404. Keep nested values on\none line inside `{ }`, as in step 2.\n\nTwo other things break parsing the same silent way: curly quotes copied from a\nrendered page, and tab characters used for indentation. Use straight quotes and\nspaces.\n:::\n\n## POS only: add POS locations to Square\n\n1.  Add each POS location to Square to generate unique Location IDs. See [add locations in Square via API](https://developer.squareup.com/docs/locations-api).\n2.  Map each Location ID to its outlet record in StoreConnect. Each outlet has a unique Salesforce ID (or SFID).\n3.  Keep both the SFID and the Location ID to hand. You need them to configure the payment provider, below.\n\n### Copy the SFID for each outlet\n\n1.  Open an outlet in StoreConnect.\n2.  In the URL shown in your browser, copy the SFID. It looks something like `a24ao000001lE6zAAE`.\n\n    ![Browser address bar with the outlet SFID highlighted in the URL](https://res.cloudinary.com/hzkr6fi81/image/upload/v1765843269/knowledge/pos/POSPaymentsOutletID_fc0oku.png)\n\n3.  Copy it for mapping to the Square Location ID in the format outlined below. If you have many store locations, map them out on a spreadsheet for verification.\n4.  Add `pos_outlets` to the **API Options** of the Square payment provider in\n    StoreConnect, alongside the options you already set:\n\n    ```yaml\n    show_wallets: true\n    location_id: YOUR_LOCATION_ID\n    pos_outlets: { a24ao000001lE6zAAE: L003B9TTM5NC5, a24ao000001gzZZAAY: L003B9TTM5NC5, default: L003B9TTM5NC5 }\n    ```\n\n    Inside `pos_outlets`, each key is an outlet SFID and each value is that\n    outlet's Square Location ID. The optional `default` key is used for any\n    outlet not listed. Keep the whole `pos_outlets` value on one line inside\n    `{ }`; see the warning in **API Options format**.\n\n5.  Save the payment provider details. The setting might now look something like this:\n\n    ![Square payment provider record in StoreConnect with API Mode, API Key, API Secret, and API Options completed](https://res.cloudinary.com/hzkr6fi81/image/upload/v1765767621/knowledge/payment-providers/Square-ProviderSetup_whv5zs.png)\n\n## POS only: add Square POS payment options as a store variable\n\n:::note\n\nLike other payment methods, the Square POS option needs to be added as a Store Variable.\nYou can do this before or after pairing a Square device at a register, but ideally\nbefore.\n\n:::\n\n1.  Open your **Store** record in StoreConnect.\n2.  Go to the **Store Variables** related list and select **New**.\n3.  Name the variable. The name is for your own reference only, so any name works. For example, `POS: Square payments`.\n4.  Enter this **Key**:\n\n    ```\n    pos.payment_options.card_square_integrated.enabled\n    ```\n\n5.  Enter `true` as the **Value**.\n\n6.  Select **Save**, then resync the register. POS reads payment settings from\n    its local cache, so a new or changed store variable is not visible on the\n    device until it resyncs.\n\n    ![Store variable record in StoreConnect with the Key and Value fields completed for Square POS payments](https://res.cloudinary.com/hzkr6fi81/image/upload/v1781677617/documentation-media/Square-Payment-Provider/Store_Variables.png)\n\n## POS only: pair Square terminal devices\n\nThe Square Terminal uses a device code and cloud pairing, so it needs internet\naccess. No USB or Bluetooth connection to the register is required.\n\n:::warning\nPairing needs genuine production credentials. Square hardware cannot be used in\nthe Sandbox, so **API Key** and **API Secret** must be the production\nApplication ID and Access Token; see the warning under **What you need**. If\n**Request a code** fails or the terminal will not accept the pairing code, check\nthe credentials and `pos_outlets` before anything in this section.\n:::\n\nThree systems are involved in setting Square up end to end, though not all\nthree come into this particular step:\n\n| System | What it is | Where it's used |\n|---|---|---|\n| **StoreConnect POS** | The POS app on your register | Request the pairing code, then confirm pairing |\n| **Square Developer Dashboard** | developer.squareup.com, used earlier in **Get Square credentials** | Not needed here. Credentials are fetched once, upfront |\n| **Square Terminal** | The physical hardware device | Enter the pairing code |\n\n1.  In StoreConnect POS, go to **Settings \u003e Payment integrations**. Square\n    appears in this list once the store variable is set and the register has\n    resynced. Select it.\n2.  Select **Request a code**. A pairing code appears, showing **Awaiting\n    pairing**.\n3.  On the physical Square Terminal, use one that isn't already signed in or\n    paired elsewhere. If it's currently signed in, **sign out** first: the\n    device code option only appears on the sign-in screen.\n4.  On the sign-in screen, choose **Use a device code**, enter the pairing code\n    from POS, and tap **Sign in**. Wait for the terminal to finish loading. It\n    should settle on a blank screen showing only the Square logo.\n5.  Back in StoreConnect POS, select **Confirm pairing**. Once pairing\n    completes, the button changes to **Disconnect**, confirming the\n    terminal is paired. Square is now available in checkout.\n\n:::tip\nBecause a paired terminal runs on production credentials, a test transaction\nmoves real money. Discount a POS product down to a token amount (for example,\n$0.25) for the test sale, then process a refund afterward to return the funds.\n:::\n\n## Check it worked\n\n1.  At the register, resync the device. POS caches payment settings locally, so\n    a newly added store variable is not visible until it resyncs.\n2.  Start a sale and go to payment. **Square** should appear as a payment option.\n3.  If it does not, check in this order:\n    1.  The store variable `pos.payment_options.card_square_integrated.enabled`\n        exists on the **Store** record with the value `true`.\n    2.  The payment provider is **Active**, and **Channels** is blank or\n        includes `pos`. Do not narrow **Channels** to `pos` on a provider that\n        also handles online payments, as that drops it out of web checkout.\n    3.  The outlet's SFID appears in `pos_outlets`, or a `default` key is\n        present. A missing entry is what makes **Request a code** return a 404.\n    4.  **API Options** parses. A nested option split across indented lines,\n        curly quotes, or tab indentation each make the whole field resolve to\n        empty with no error on the record.\n    5.  If you are pairing a physical terminal: **API Key** and **API Secret**\n        are genuinely the production Application ID and Access Token. See the\n        warning under **What you need**."}