billingHelp

Square OAuth application

The Square developer application for OAuth, its redirect URL, application secret, webhook subscription, the permissions asked of sellers, tokens and locations.

With Square OAuth the owner of a workspace signs in to Square and authorizes the platform's application. Square returns an access token for that seller, which this system stores encrypted, renews weekly and uses for the seller's payment links, subscriptions, refunds and disputes.

Create the application#

  1. Sign in at developer.squareup.com with the platform's Square account and create an application.
  2. Open OAuth. For Sandbox, then for Production:
    • copy the Application ID and the Application secret;
    • set the Redirect URL to the address shown as OAuth redirect URL on the application's page here.

Add the application#

Super → Platform apps → Square: Application ID and Application secret. Save, then Verify.

Square has no call that checks an application secret on its own. Verify checks the form of the values for the environment; the secret is proven the first time a workspace connects.

Register the webhook subscription#

Application → Webhooks → Subscriptions → Add subscription:

  1. Notification URL — the Platform webhook endpoint shown on the application's page, exactly as shown: Square signs the URL together with the body.
  2. Select the events listed under Events to send: oauth.authorization.revoked and the payment events.
  3. Open the subscription and copy its Signature key into the application.

What a workspace does#

Settings → Gateways → Connect Square. Square shows the permissions the application asks for:

MERCHANT_PROFILE_READ, PAYMENTS_READ, PAYMENTS_WRITE, ORDERS_READ, ORDERS_WRITE, ITEMS_READ, ITEMS_WRITE, CUSTOMERS_READ, CUSTOMERS_WRITE, SUBSCRIPTIONS_READ, SUBSCRIPTIONS_WRITE, INVOICES_READ, DISPUTES_READ.

After Allow, the set is Enabled when the account has an active US-dollar location with card processing. The first such location is chosen; an account with several can pick another on the set's page. Without one the set is Restricted.

In the sandbox, Square only authorizes while the sandbox test account's Seller Dashboard is open in the same browser (Developer Console → Sandbox test accounts → Open).

Tokens#

  • The access token lives 30 days. The hourly job connect.sync renews every token older than 7 days, as Square recommends.
  • If renewal keeps failing and the token runs out, the set leaves service and the owners are e-mailed; connecting again repairs it.
  • Disconnect revokes the application's access at Square and erases the tokens here. A seller who removes the application in Square causes oauth.authorization.revoked, with the same result.

Go live#

  • [ ] Production Application ID and secret in a Live application; the production Redirect URL registered.
  • [ ] A production webhook subscription with the live application's URL and its signature key.
  • [ ] One seller connected, one small real payment and refund.

Common errors#

"This connection link is not valid any more" — the authorization came back after 30 minutes, was opened twice, or by another member than the one who started it. Start again.

"Square did not complete the authorization" — usually the Redirect URL registered at Square differs from the one shown here, or the secret is from the other environment. The set's page shows Square's own message.

Restricted: no active US-dollar location — the Square account needs a location in USD with card processing enabled.