Square App Configuration

This guide explains how to connect your Square account to the app, set up the Square webhook, and assign Square connections to Saleor channels.

App configuration is based on three entities:

Square connections: credentials for a Square application and location
Square webhooks: one subscription per Square application and environment that sends payment and refund updates to the app
Channel assignments: the mapping between a Saleor channel and a Square connection

You can add multiple connections. A connection isn’t used until it’s assigned to a channel. Each channel can be assigned to only one connection.

To configure the app, open Extensions in the Saleor Dashboard and select the installed Square app.

Before you start

You need a Square application in the Square Developer Console. Open your application and collect the following values for the environment you want to use (sandbox or production):

Application ID, from the Credentials page
Access token, from the Credentials page
Location ID, from the Locations page

Adding a Square connection

In the Square connections section, click Add connection and fill in the form:

Connection name: A label that helps staff users tell connections apart, for example “Sandbox” or “Production US”
Environment: Sandbox or Production. It must match the environment of the credentials.
Application ID: The Square application ID. It’s sent to the storefront to initialize the Square Web Payments SDK.
Location ID: The Square location that receives the payments. The location’s country decides which wallets are available.
Access token: The Square access token. It’s stored encrypted and is never sent to the storefront.

Click Create connection to save it.

The app doesn’t verify the credentials when you save them. Test a payment after you finish the configuration. If the access token is wrong, the app reports a problem in the Dashboard on the first failed payment.

A connection is identified by its environment, application ID, and location ID. Adding a connection with the same three values replaces the existing one, and keeps its channel assignments. Deleting a connection also removes its channel assignments.

Rotating the access token

To replace the access token, click Add connection and enter the same environment, application ID, and location ID with the new access token. The app replaces the stored token. Channel assignments stay unchanged, and earlier payments remain refundable.

To move a channel to a different Square application or location, add a new connection and assign the channel to it. Keep the old connection while you may still need to refund payments made with it.

Setting up the Square webhook

Square sends payment and refund updates to the app through a webhook subscription. The app needs it to:

Resolve payments whose outcome was unknown during checkout
Reflect refunds made in the Square Dashboard
Update refunds that Square processes asynchronously

In the Square webhooks section, the app lists one row per Square application and environment used by your connections. Click Set up webhook to create the subscription.

The app creates a subscription for the payment.updated and refund.updated events and stores its signature key encrypted. You can check it in the Webhooks page of your application in the Square Developer Console.

Use Update webhook to repair the subscription, for example after the app URL changed. Use Remove webhook to delete it.

If Square has more than one subscription for this installation, the app lists them so you can remove the duplicates.

Assigning a connection to a channel

In the Channel assignments section, select a connection for each channel that should offer Square at checkout. A channel set to Not assigned doesn’t offer Square.

Changes apply to new payments only. Payments that already started keep using the connection they were created with.

Ensure the channel has its transaction flow set to CHARGE and has Use Transaction flow when marking order as paid enabled in the channel settings.

Reinstalling the app

Reinstalling the app doesn’t restore the previous configuration. To keep processing payments and refunds made before reinstallation:

Add a connection with the same environment, application ID, and location ID as before.
Assign the channels again.
Set up the Square webhook again.

The app removes the webhook subscription of the previous installation the next time Square delivers an event to it.