Square Setup

Square handles checkout, paying an invoice from the client portal, saving a card and background renewal charges. It differs from the other gateways in one important way: a Square account is tied to a location, and that location decides which currency you can take and whether card processing is switched on at all. This article covers the setup, the location trap, and 3-D Secure. It is written for operators.

Before you start #

• A Square account with an application created in the Square Developer Dashboard.
• The application’s Application ID and an Access Token, both from the same environment (Sandbox or Production).
• The Location ID of the location you want to take money through.
• Access to Billing → Payment Gateways in RackHelm, which in a default install means a Super Admin account.

Step 1 — Add the gateway #

1. Open Billing → Payment Gateways.
2. Select Add Gateway and choose Square, or Configure on the Square row.
3. Paste the Application ID. This one is public: the browser uses it to load Square’s card form.
4. Paste the Access Token. This one is secret and does the charging.
5. Paste the Location ID.
6. Set Mode to match the environment your credentials came from.
7. Tick Enable Gateway and select Save Changes.

Warning: The Application ID and the Access Token must come from the same environment. A sandbox Application ID with a production token authenticates fine and then fails when the card form loads, which looks like a browser fault rather than a configuration one. The connection test catches this and says the Application ID is for the other environment.

Step 2 — Decide who can see it #

Square gateways added from this release on start as Staff only, so you can test on the live site before customers are offered it.

1. Find Who may use it in the gateway dialog.
2. Leave it on Staff only while testing.
3. Switch to Everyone when you are satisfied, and save.

Step 3 — Run Test connection, and do not skip it #

For Square the connection test is not optional housekeeping. It is how RackHelm learns your location’s currency. Until it has run, Square is offered in the store’s base currency only.

1. Select Test connection.
2. RackHelm checks the token, looks the location up, confirms the location is active and that card processing is enabled on it, and checks the Application ID’s environment.
3. On success it stamps the gateway with the location’s currency, the time and the environment verified.

What the failures mean:

Note: The test covers the Application ID, the Access Token, the Location ID and the Mode as a set. Change any one and run it again, or the stored currency may describe the old location.

Step 4 — Upgrading an existing Square gateway #

If you configured Square before this release, open it and run Test connection once. Without it the gateway has no recorded location currency and will only be offered in your base currency, even to customers whose account is set to something else.

Currency #

A Square location takes one currency. RackHelm will not offer a customer a card they could never be charged on: if their account currency does not match, Square is simply not shown, and an attempt to save a card in that currency is refused with:

Card payments through Square are not available for your account currency.

To take more than one currency through Square you need a Square location per currency, and a RackHelm gateway per location.

3-D Secure #

When the customer’s bank asks for it, Square runs the 3-D Secure challenge in the browser before the charge is attempted, as UK and EU rules require. Nothing needs switching on — it happens when the bank demands it. A saved card that later needs a challenge cannot be charged unattended; that renewal is held for staff rather than retried.

What Square is used for, and how #

Note: RackHelm only retires a saved card when Square says that specific card is gone. A location problem or another configuration fault no longer causes a customer’s working card to be deleted.

Troubleshooting #