---
title: "Integrating Square"
slug: "integrating-square"
updated: 2024-12-27T15:47:43Z
published: 2024-12-27T15:47:43Z
canonical: "docs.newstore.com/integrating-square"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating Square

Square is an alternative `payment service provider` (PSP) that retailers can use to accept in-store card payments in markets where Adyen does not support in-store payments. For example, Square POS is used at NewStore for retailers with stores in Japan.

To integrate with a PSP for the United States or Europe, see [Integrating Adyen](/v1/docs/integrating-adyen#integ-adyen).

To accept payments via Square and enable NewStore to seamlessly trigger notifications, payments, and refunds in Square directly via NewStore Associate App, the retailer must set up Square and NewStore separately.

## Limitations of Square as a payment provider

1. Store associates must download a separate Square POS app on the same iPhone where NewStore Associate App is installed to accept card payments.

> [!TIP]
> Note
> 
> - Currently, Square only accepts card payments in Japan via the Square POS integration and not the NewStore SDK integration. See [Setting up Square](/v1/docs/integrating-square#setting-up-square).
> - Ensure that store associates only use split payments in NewStore Associate App. In the Square POS app, split payments are not supported via the Square integration at NewStore.
2. All Square POS payments are immediately captured.
3. Square does not support refunds without the original payment reference. To refund a return that does not have the original Square payment reference, use a different payment method, such as a gift card or cash.

## Prerequisites

Before setting up Square, request the following from NewStore:

- The URL for NewStore Associate App. For example, `com.newstore.associate.<retailer_name>`.
- The NewStore Associate App URL scheme, for example `com.newstore.square`.

Once you have received both values from NewStore, follow the setup instructions in the order provided below.

## Setting up Square

1. In the Square developer portal, create a Square business application in your business account.

To create a new application, follow the instructions specified in the official [documentation](https://squareup.com/developers). Square generates the information needed for integrations.
2. Create store locations in Square for the physical stores where you want to use Square POS to accept payments. See the location documentation from Square.

> [!TIP]
> Note
> 
> Securely send the mapping of the store name against the store location IDs specified in Square to your contact point in NewStore. This allows NewStore to verify the store associates logged into the store location in Square.
3. Retrieve the application ID, access token, and Signature Key to send to your NewStore contact. This enables NewStore to connect to Square and:
  - Retrieve payment information and start payment operations with Square API. See [Configuring the Square API](/v1/docs/integrating-square#configuring-the-square-api).
  - Receive notifications from Square. See [Configuring notifications from Square](/v1/docs/integrating-square#configuring-notifications-from-square).

> [!NOTE]
> Important
> 
> Contact Square to suppress receipt generation in Square. This avoids receiving two two different receipts from NewStore and Square, which may cause confusion for the customer.

### Configuring notifications from Square

For NewStore to receive notifications from Square:

1. Access the [Square Portal](https://developer.squareup.com/apps/).
2. Select the application.

1. In the `Webhooks` section, click `Add endpoint`.
2. For the new method you want to add, use the following values:

| Feature/Property | Value |
| --- | --- |
| `NAME` | NewStore |
| `URL` | `https://<retailer>.<short stage id>.newstore.net/_/v1/org/psps/square/notifications` |
| `VERSION` | 2020-06-25 |
| `Events` | `payment.created`, `payment.updated`, `refund.created`, and `refund.updated` |
3. Copy the value of `SIGNATURE KEY` and securely send it to your contact point at NewStore.

### Configuring the Square API

NewStore also needs to be able to retrieve payment information and request refunds using the [Square PSP API](https://docs.newstore.net/private-api/payments/psp_square_api). To allow NewStore to perform [Square PSP API](https://docs.newstore.net/private-api/payments/psp_square_api) requests:

1. Access the [Square Portal](https://developer.squareup.com/apps/).
2. Select the application.

1. In the `Credentials` section, copy the values specified in `Application ID` and `Access Token`.

> [!TIP]
> Note
> 
> To test the POS API or for live sales transactions, you need Square production credentials. Before copying the values for application ID and access token, ensure that `Production Settings` is displayed in the lower left corner of the page. If `Sandbox Settings` is displayed, click the label and the environment automatically switches to production.
2. Securely send both values to your contact point at NewStore.

### Configuring locations in Square

NewStore must be able to correlate stores with the locations configured on Square. To view the configured locations:

1. Access the [Square Portal](https://developer.squareup.com/apps/).
2. Select the application.
3. Specify NewStore Associate App to be allowed to be called via the Square POS app to ensure only NewStore Associate App can trigger a payment in Square:

For more information, see the [Square documentation](https://developer.squareup.com/docs/get-started).
  1. In the left navigation bar, select `Point of Sale API`.
  2. For `iOS App Bundle IDs`:

This value is provided by NewStore.
    - Specify `com.newstore.associate.<retailer_name>`, if you use NewStore SDK.
    - Specify `com.newstore.associate-one`, if you use NewStore Associate App v1.0.0 or later.
  3. For `iOS App URL Schemes`:

This value is provided by NewStore.
    - Specify `com.newstore.square`, if you use NewStore SDK.
    - Specify `com.newstore.associate-one.square`, if you use NewStore Associate App v1.0.0 or later.
4. In the `Locations` section, each location has a unique `Location ID`. These values should be added to NewStore as described in [Configuring Square as a payment provider](/v1/docs/configuring-square-as-a-payment-provider#config-square).

## Setting up NewStore to connect with Square

> [!WARNING]
> Supported from
> 
> This feature is supported from NewStore SDK v23.1.0 and later.

To set up NewStore to connect with Square, see [Configuring Square as a payment provider](/v1/docs/configuring-square-as-a-payment-provider#config-square) and [Configuring payment options](/v1/docs/configuring-payment-options#config-payment-options).

## Installing Square apps on the associate's iPhone

To allow associates to use Square POS on their iPhone for payments during checkout in NewStore:

1. Order Square devices. We strongly recommend ordering one device for each iPhone that NewStore Associate App is installed on, as a Square device can only be paired with one Square POS at a given time.
2. Install the Square POS app. See the [Square guide](https://squareup.com/help/us/en/article/5243-download-the-square-app).
3. Select your store location from the list of available of store locations.
4. Configure Square POS settings in the associate’s iPhone:

> [!TIP]
> Note
> 
> To ensure that the checkout process is completed in the NewStore platform after payment with Square, the `Skip receipt screen` button must be enabled in Square POS for each associate’s iPhone. See the [Signature and receipt documentation](https://squareup.com/help/ca/en/article/5684-skip-the-receipt-screen-to-speed-up-checkout) from Square.

## Testing and going live with integrated payments via Square POS

You can only test payments via Square POS in the production environment, as Square does not support a sandbox testing environment.

After you have configured Square POS in NewStore (see the [guide](/v1/docs/integrating-square#setting-up-newstore-to-connect-with-square) ), connect Square webhooks to your production environment. See the webhooks documentation from Square.

> [!TIP]
> Note
> 
> Square has only one environment available for testing payments. When multiple environments at NewStore are connected to one Square application, each NewStore environment can only process Square notifications that originate from the same environment.

**Related topics**

- [Integrating a payment service provider](/v1/docs/integrating-a-payment-service-provider#integ-psp)
- [Integrating Adyen](/v1/docs/integrating-adyen#integ-adyen)
- [Square PSP API](https://docs.newstore.net/private-api/payments/psp_square_api)