> For the complete documentation index, see [llms.txt](https://docs.boomerangme.cards/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.boomerangme.cards/marketplace/square-pos-app.md).

# Square POS app

Boomerang has two Square integrations. Pick the one that matches what you need:

|                       | [**Square Loyalty**](https://docs.boomerangme.cards/integrations/square-loyalty) | **Square POS app** (this page)                                                             |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| What it does          | Keeps customers, points and rewards in sync between Square Loyalty and Boomerang | Adds stamps, points, cashback or discount to a Boomerang card for purchases paid in Square |
| Card types            | Reward                                                                           | Stamp, reward, cashback, discount                                                          |
| Square Loyalty needed | Yes                                                                              | No                                                                                         |
| Setup                 | Sign in to Square from Boomerang                                                 | Create a Square developer app, enter its credentials in Boomerang, add a webhook           |

**Important:** don't connect the same card to both integrations. A purchase would earn points twice: once from the app, and once more from Square Loyalty itself.

The Square POS app works in one direction, from Square to Boomerang. When a payment is completed in Square, Boomerang finds the customer's card and adds stamps, points, cashback or discount according to the card settings. When the payment is refunded, Boomerang takes back what it earned. Rewards can't be redeemed in Square. Staff redeem them in Boomerang with the Scanner App.

The integration with **Square Marketplace** is a one-way connection where all transaction data flows from Square to Boomerang. This integration works only with the following Boomerang card types: **stamp, cashback, discount, and reward**. Based on the purchase data received from Square, the system automatically applies the earning logic defined for these card types.\
Please note that reward redemption or benefits cannot be processed inside Square — all redemptions must be completed through the **our Scanner App**.

### Before you start

You need a Square account (production, not sandbox) and an active Boomerang card of one of the types below.

**How each card type earns:**

| Card type | Earns from Square purchases                     | Doesn't earn                    |
| --------- | ----------------------------------------------- | ------------------------------- |
| Stamp     | Stamps per visit (purchase) or per amount spent | Custom accrual, stamps per item |
| Reward    | Points per amount spent or per visit            | Points program, points per item |
| Cashback  | Yes                                             |                                 |
| Discount  | Yes                                             |                                 |

* **How much a purchase earns is set in the card settings**, for example "10 points for every $1". The app setup only shows this value. To change it, edit the card.
* **The currency must be the same** in Boomerang and in Square.
* **To send customers a link to install the card,** connect an email provider (for email) or a Twilio account (for SMS) in Boomerang.

### Step 1. Create a Square app

1. Open <https://developer.squareup.com/console/en/apps> and sign in with the Square account you sell with. Type the address in the browser: the Square Dashboard doesn't link to this page.
2. Click **+** and enter a name for the application.

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2F4KXlwMXX5wyJnJjpbyG6%2FScreenshot%20at%20Nov%2014%2021-08-07.png?alt=media&amp;token=08a25861-1fbb-4ac3-aa22-b853397f2e2a" alt=""><figcaption></figcaption></figure>

Enter the name of the application

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FQ7YjZmap9qiuj1iN30bZ%2FScreenshot%20at%20Nov%2014%2021-09-21.png?alt=media&amp;token=7f0d441c-8efe-4bcf-82de-9e0b64c13627" alt=""><figcaption></figcaption></figure>

3. The next two screens (audience and use cases) are optional. Your answers don't affect the integration.

<div><figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2Fw7hsOnqrMblhVCR8WObg%2FScreenshot%20at%20Nov%2015%2010-12-13.png?alt=media&amp;token=d27aaa6e-c38e-4b6b-8e96-e5e8d94b3b56" alt=""><figcaption></figcaption></figure> <figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FsZIAzVMiFAOmvPqLiuJu%2FScreenshot%20at%20Nov%2014%2021-10-20.png?alt=media&amp;token=0fffa73f-9d39-44d0-b589-96c954caaf30" alt=""><figcaption></figcaption></figure></div>

4.The application opens on the **Credentials** page. Switch to **Production** at the top and copy the **Production access token**.

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FftSOs4NCfnvXATSAhQii%2Fimage.png?alt=media&amp;token=ca96ef86-f1ab-41f6-80c1-90e42ef29842" alt=""><figcaption></figcaption></figure>

**Important:** the access token gives full access to your Square account, so don't share it. If you replace the token in Square, update it in Boomerang too (see Change settings). Until you do, purchases don't earn anything.

### Step 2. Find your merchant ID

The Developer Console doesn't show your merchant ID. Get it with Square's API Explorer:

1. Open Square's API Explorer and go to **Merchants → List merchants**.
2. Paste your production access token, select the **Production** environment, and click **Run**.
3. Copy the `id` value from the response. It looks like `ML1A2B3C4D5E6`.

**Tip:** if Square Loyalty is already connected in Boomerang, the merchant ID is shown under **Square** in **Settings → Integrations → Active integrations**.

### Step 3. Add a webhook in Square

1. In your Square application, go to **Webhooks → Subscriptions** and click **Add subscription**. Make sure **Production** is selected, the same environment as your access token.
2. **Subscription name:** any name, for example `Boomerang`.
3. **Notification URL:** `https://square.apps.digitalwallet.cards/square/webhook`

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FF33iYGE83DjlE5sIOUDY%2Fimage.png?alt=media&amp;token=cabfb889-ffb3-4794-8ac4-fc178df3c4e6" alt=""><figcaption></figcaption></figure>

4. **API version:** keep the default.
5. **Events:** select only these four:

* `payment.created`
* `payment.updated`
* `refund.created`
* `refund.updated`

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FZGrs9097LEiII9sKUK6U%2Fimage.png?alt=media&amp;token=7b729e4c-777d-451a-a0d0-0ad3b13ba716" alt=""><figcaption></figcaption></figure>

6. Click **Save**.

### Step 4. Install the app in Boomerang

1. In Boomerang, go to **Settings → Integrations**. Under **Apps setup**, find **Square** and click **Install**.
2. **Template** (stamp, cashback, discount or reward)**:** select the card that purchases should earn on. **Note** with stamp and points mechanics (in stamp and reward cards) accrual should be done through the scanner, automatic accrual will not be done through the marketplace.&#x20;

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FXYAXjYONqRImx9DFbYlj%2Fimage.png?alt=media&amp;token=d27fe361-195e-4710-84eb-424e4fce133b" alt=""><figcaption></figcaption></figure>

3. **Credentials:** enter the **merchant ID** and the **Square API access token**, then click **Next**. Boomerang checks them with Square. Enter the merchant ID(your saved integration ID in step one) and Square APP Access Token

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FEtELOlqMPy7KtJOD0PmL%2FScreenshot%20at%20Nov%2014%2021-15-45.png?alt=media&amp;token=8c1e9317-433c-4bfa-a8b3-6e6bab51d827" alt=""><figcaption></figcaption></figure>

4. **Location:** Square skips this step.
5. **Accrual rules:** the wizard shows how the card earns, for example "10 points for every $1". Choose which purchases count:
   * **Whole check:** every purchase counts in full.
   * **Checks over a certain amount:** only checks of at least the amount you enter count. They count in full.
   * **Specific items:** only the items you select count. The list comes from the item library of your Square account. Items with variations are shown as groups.

<div><figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FlT5Wn2IwTmwICJ4SjI4n%2FScreenshot%20at%20May%2023%2017-16-18.png?alt=media&amp;token=e6fef5b8-9cdf-4caf-ae5e-bfd4a461f50a" alt=""><figcaption></figcaption></figure> <figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FPSOVYDg6SPnkvVYEn589%2FScreenshot%20at%20May%2023%2017-16-31.png?alt=media&amp;token=c5d1b8de-ce3a-4b1b-954c-271e81f19548" alt=""><figcaption></figcaption></figure> <figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2F9GVDZFDEiJQhZmaWJVSm%2FScreenshot%20at%20May%2023%2017-16-43.png?alt=media&amp;token=594680cd-906a-4e72-8497-5ba532ef50be" alt=""><figcaption></figcaption></figure></div>

6. **Delivery channels:** choose how new customers get the link to install the card. **Email** needs a connected email provider, and **SMS** needs a connected Twilio account.

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FhQBbSiFGSXpR7nZMl8iW%2Fimage.png?alt=media&amp;token=e1389a7e-0c77-4401-863e-03b3f5f546e1" alt=""><figcaption></figcaption></figure>

7. Click **Next**. The app appears in **Active apps** with the card, the accrual rule and the delivery channels.&#x20;

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2F0Y9XeNpiOMVnM1kJp9Dj%2Fimage.png?alt=media&amp;token=24d725d5-3aab-498b-87ff-7eaf6541be22" alt=""><figcaption></figcaption></figure>

### How purchases earn

* **Add the customer to the sale in Square.** The app reads the phone number and email of the customer attached to the order. **If no customer is attached, the purchase earns nothing.**
* Only completed payments count, and each payment counts once.
* Boomerang looks for the customer's card for the selected template by phone number or email. If there isn't one, Boomerang creates the customer, issues the card, and sends the install link to the selected delivery channels.
* **Refunds:** when a refund is completed in Square, Boomerang takes back everything the payment earned, even if only part of the payment was refunded.

### Change settings

In **Settings → Integrations → Active apps**, click the edit icon next to the app. There you can change the card, the credentials, the accrual rule and the delivery channels.

<figure><img src="https://121681468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBfW4nnOu4AysbkbyxNug%2Fuploads%2FTXVvIFECUhqALMwbu2FY%2Fimage.png?alt=media&amp;token=2f42f23b-019c-48fa-8223-a0df6dfdde03" alt=""><figcaption></figcaption></figure>

### Remove the app

1. In **Settings → Integrations → Active apps**, delete the app.
2. In Square, delete the webhook subscription. Otherwise Square keeps sending every payment to Boomerang.

#### Why the integration isn't working: <a href="#why-the-integration-isnt-working" id="why-the-integration-isnt-working"></a>

* **No customer was attached to the sale in Square,** or that customer has no phone number or email.
* **The currencies don't match.** Boomerang and Square must use the same currency.
* **The access token or the webhook is in Sandbox.** Both must be in Production.
* **The merchant ID is wrong,** or the access token was replaced in Square and not updated in Boomerang.
* **The webhook is set up incorrectly.** Check the notification URL and the four events.
* **The card's accrual type isn't supported.** See Before you start.
* **The accrual rule excludes the purchase.** The check is below the minimum amount, or it has none of the selected items.
* **The customer didn't get the install link.** No email provider or Twilio account is connected.

<br>
