# Square Source: https://support.storeconnect.com/articles/square-payment-provider · Last modified 21 August 2026 Square is a third party payment provider. If you use Square, you can integrate it directly with StoreConnect. Square works for: - Standard checkout transactions - Subscription payments - Apple Pay and Google Pay transactions - Pre-authorization - 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) - In-person card payments on [Square Terminal](https://squareup.com/us/en/campaigns/switch-to-terminal) devices, paired to a StoreConnect register :::tip Already have your credentials? Go to [Configure Square in StoreConnect](#configure-square-in-storeconnect). ::: ## What you need 1. A Square developer account. 2. Square credentials and location IDs. 3. A sandbox environment (recommended). 4. Outlets set up in StoreConnect (POS only). 5. Minimal code and admin know-how. :::warning A physical Square Terminal cannot pair using sandbox credentials. Use the production Application ID and Access Token from Square's **Credentials** page for **API Key** and **API Secret**. See Square's [Sandbox overview](https://developer.squareup.com/docs/devtools/sandbox/overview) and **Testing in sandbox** below. Sandbox is fine for testing the online storefront. **API Mode** does control which Square environment online payments use, so set it to `production` for a live store. Terminal pairing always runs against Square production, so pairing succeeds or fails on the credentials themselves, not on this field. ::: ## Get Square credentials 1. 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). 2. 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. :::tip Set up a sandbox first to test it works how you want, then update to the production credentials later. ::: 3. In Square, go to the **Credentials** page of your app. ![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) 4. Copy the **Application ID** and **Access Token**. 5. Go to the **Locations** section and copy the **Location ID**. ![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) :::note Sandbox and production are separate Square environments: credentials, Location IDs, and other resources from one **cannot** be used with the other. If you switch API Mode from sandbox to production later, you need a fresh Application ID, Access Token, and Location ID from the production app, not just a mode toggle. ::: ## Testing in sandbox Square's Sandbox is a free, isolated environment for testing without moving real money. See Square's own [Sandbox overview](https://developer.squareup.com/docs/devtools/sandbox/overview) and [Sandbox payments](https://developer.squareup.com/docs/devtools/sandbox/payments) docs for the full reference. A few things that matter for a StoreConnect setup: - **Card-not-present (online storefront) testing is supported.** Use Square's test card numbers to trigger predictable outcomes at checkout: | Card | Number | CVV | Result | |---|---|---|---| | Visa | `4111 1111 1111 1111` | `111` | Approved (any future expiry) | | Mastercard | `5105 1051 0510 5100` | `111` | Approved (any future expiry) | | Visa | `4000 0000 0000 0002` | `111` | Declined | Postal code `99999` and expiry `01/40` simulate a postal-code or expiration-date error respectively. - **Card-present (POS terminal) testing is not supported at all**, in any form. Square's own docs are explicit: "Square hardware, such as a POS terminal, cannot be used in the Sandbox," and "Testing card-present scenarios is currently not supported." This is the same limitation behind the production-credentials requirement for pairing a physical terminal; see the warning under **What you need**. ## Configure Square in StoreConnect 1. Open StoreConnect and go to **Settings > Payments > Payment providers**. 2. Select **New**. Complete the fields as follows, then **Save**: | StoreConnect field | Square data | |---|---| | **Name** | Square. For a test provider, add `- Test`. | | **Provider** | Select Square from the list. | | **API Mode** | Enter `sandbox` or `production`. | | **API Key** | The **Application ID** from your Square account. | | **API Secret** | The **Access Token** from your Square account. | | **API Options** | See **API Options format** below. | ### API Options format 1. Enter the options as YAML key/value pairs, one option per line. JSON is valid YAML, so a braced object parses the same way: ```yaml show_wallets: true location_id: YOUR_LOCATION_ID ``` 2. For an option that holds a set of values, such as `pos_outlets`, write the nested keys on one line inside `{ }`: ```yaml show_wallets: true location_id: YOUR_LOCATION_ID pos_outlets: { a24ao000001lE6zAAE: L003B9TTM5NC5, default: L003B9TTM5NC5 } ``` All options live in one **API Options** value. Add new options to what is already there rather than replacing it. 3. Add only the options you need: | Option | Purpose | |--------|---------| | `location_id` | The Square Location ID for online payments. POS ignores this and takes its location from `pos_outlets`. | | `show_wallets` | Set `true` to show Apple Pay and Google Pay at checkout. | | `pos_outlets` | Maps each StoreConnect outlet to a Square Location ID for POS (see below). | A web-only store needs `location_id`. A POS-only store needs `pos_outlets`. A store that takes both needs both. :::warning Do not split a nested option across indented lines. This form looks correct and fails: ```yaml pos_outlets: a24ao000001lE6zAAE: L003B9TTM5NC5 default: L003B9TTM5NC5 ``` Line breaks that follow a key are normalized before the field is parsed, which can collapse the indented block into a single invalid line. The whole field then resolves to empty: no error appears on the record, and POS calls that need `pos_outlets` (including terminal pairing) return a 404. Keep nested values on one line inside `{ }`, as in step 2. Two other things break parsing the same silent way: curly quotes copied from a rendered page, and tab characters used for indentation. Use straight quotes and spaces. ::: ## POS only: add POS locations to Square 1. 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). 2. Map each Location ID to its outlet record in StoreConnect. Each outlet has a unique Salesforce ID (or SFID). 3. Keep both the SFID and the Location ID to hand. You need them to configure the payment provider, below. ### Copy the SFID for each outlet 1. Open an outlet in StoreConnect. 2. In the URL shown in your browser, copy the SFID. It looks something like `a24ao000001lE6zAAE`. ![Browser address bar with the outlet SFID highlighted in the URL](https://res.cloudinary.com/hzkr6fi81/image/upload/v1765843269/knowledge/pos/POSPaymentsOutletID_fc0oku.png) 3. 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. 4. Add `pos_outlets` to the **API Options** of the Square payment provider in StoreConnect, alongside the options you already set: ```yaml show_wallets: true location_id: YOUR_LOCATION_ID pos_outlets: { a24ao000001lE6zAAE: L003B9TTM5NC5, a24ao000001gzZZAAY: L003B9TTM5NC5, default: L003B9TTM5NC5 } ``` Inside `pos_outlets`, each key is an outlet SFID and each value is that outlet's Square Location ID. The optional `default` key is used for any outlet not listed. Keep the whole `pos_outlets` value on one line inside `{ }`; see the warning in **API Options format**. 5. Save the payment provider details. The setting might now look something like this: ![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) ## POS only: add Square POS payment options as a store variable :::note Like other payment methods, the Square POS option needs to be added as a Store Variable. You can do this before or after pairing a Square device at a register, but ideally before. ::: 1. Open your **Store** record in StoreConnect. 2. Go to the **Store Variables** related list and select **New**. 3. Name the variable. The name is for your own reference only, so any name works. For example, `POS: Square payments`. 4. Enter this **Key**: ``` pos.payment_options.card_square_integrated.enabled ``` 5. Enter `true` as the **Value**. 6. Select **Save**, then resync the register. POS reads payment settings from its local cache, so a new or changed store variable is not visible on the device until it resyncs. ![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) ## POS only: pair Square terminal devices The Square Terminal uses a device code and cloud pairing, so it needs internet access. No USB or Bluetooth connection to the register is required. :::warning Pairing needs genuine production credentials. Square hardware cannot be used in the Sandbox, so **API Key** and **API Secret** must be the production Application ID and Access Token; see the warning under **What you need**. If **Request a code** fails or the terminal will not accept the pairing code, check the credentials and `pos_outlets` before anything in this section. ::: Three systems are involved in setting Square up end to end, though not all three come into this particular step: | System | What it is | Where it's used | |---|---|---| | **StoreConnect POS** | The POS app on your register | Request the pairing code, then confirm pairing | | **Square Developer Dashboard** | developer.squareup.com, used earlier in **Get Square credentials** | Not needed here. Credentials are fetched once, upfront | | **Square Terminal** | The physical hardware device | Enter the pairing code | 1. In StoreConnect POS, go to **Settings > Payment integrations**. Square appears in this list once the store variable is set and the register has resynced. Select it. 2. Select **Request a code**. A pairing code appears, showing **Awaiting pairing**. 3. On the physical Square Terminal, use one that isn't already signed in or paired elsewhere. If it's currently signed in, **sign out** first: the device code option only appears on the sign-in screen. 4. On the sign-in screen, choose **Use a device code**, enter the pairing code from POS, and tap **Sign in**. Wait for the terminal to finish loading. It should settle on a blank screen showing only the Square logo. 5. Back in StoreConnect POS, select **Confirm pairing**. Once pairing completes, the button changes to **Disconnect**, confirming the terminal is paired. Square is now available in checkout. :::tip Because a paired terminal runs on production credentials, a test transaction moves real money. Discount a POS product down to a token amount (for example, $0.25) for the test sale, then process a refund afterward to return the funds. ::: ## Check it worked 1. At the register, resync the device. POS caches payment settings locally, so a newly added store variable is not visible until it resyncs. 2. Start a sale and go to payment. **Square** should appear as a payment option. 3. If it does not, check in this order: 1. The store variable `pos.payment_options.card_square_integrated.enabled` exists on the **Store** record with the value `true`. 2. The payment provider is **Active**, and **Channels** is blank or includes `pos`. Do not narrow **Channels** to `pos` on a provider that also handles online payments, as that drops it out of web checkout. 3. The outlet's SFID appears in `pos_outlets`, or a `default` key is present. A missing entry is what makes **Request a code** return a 404. 4. **API Options** parses. A nested option split across indented lines, curly quotes, or tab indentation each make the whole field resolve to empty with no error on the record. 5. If you are pairing a physical terminal: **API Key** and **API Secret** are genuinely the production Application ID and Access Token. See the warning under **What you need**. --- ## Follow StoreConnect - [Email Newsletter](https://getstoreconnect.com/c/lp-newsletter) - [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464) - [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g) - [LinkedIn](https://www.linkedin.com/company/storeconnect) - [X / Twitter](https://x.com/storeconnecthq) ## Popular Links - [Partners](https://getstoreconnect.com/partners) - [News](https://getstoreconnect.com/articles/news) - [Events](https://getstoreconnect.com/articles/events) - [Feature Comparison](https://getstoreconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://getstoreconnect.com/contact) ## Documentation - [Help documentation](https://support.storeconnect.com/help-documentation) - [AI agents](https://support.storeconnect.com/ai) - [Videos & tutorials](https://support.storeconnect.com/videos-tutorials) - [Developer reference](https://support.storeconnect.com/developer-reference) - [Release notes](https://support.storeconnect.com/release-notes) - [Troubleshooting](https://support.storeconnect.com/troubleshooting) - [Trust Center](https://trust.getstoreconnect.com/) - [Status Page](https://status.storeconnect.com/) ## Contact - info@getstoreconnect.com - US +1 415 745 3230 - AUS +61 2 8365 2308 100 S Ashley Dr, Suite 600-2461 Tampa FL 33602-600 USA Level 22, Sydney Place 180 George Street Sydney, NSW, 2000, AUS --- StoreConnect Support — https://support.storeconnect.com/articles/square-payment-provider