Authorize your Android Application

Link to section


To enable your application to securely connect to any Square seller account, the Mobile Payments SDK must be authorized using an OAuth access token and a location ID. Each Square seller who uses your application must be authorized with an OAuth access token. The same process should be used even if you only plan to use the Mobile Payments SDK with your own Square account. To get started, see OAuth documentation and OAuth sample applications.

When requesting an OAuth access token from a seller, your application must request the following permissions:

  • MERCHANT_PROFILE_READ is required to get a list of all of a seller's locations.
  • PAYMENTS_WRITE and PAYMENTS_WRITE_IN_PERSON are required to take payments with the Mobile Payments SDK.
  • PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS is required if you want to collect application fees.

The Mobile Payments SDK is divided into four managers to provide specific areas of functionality. Authorization is handled by the AuthorizationManager. Use AuthorizationManager.authorize() to authorize your Mobile Payments SDK application with a Square seller's token and locationId. You also pass in a callback to be notified of authorization errors and display those to the user.

Link to section

Authorization state

You can check whether a user of your application is authorized by checking AuthorizationState.isAuthorized() prior to beginning authorization. However, this value isn't modified if the state changes.

To asynchronously track changes in the authorization state, register a callback by using AuthorizationManager.setAuthorizationStateChangedCallback(). This callback can give you live updates to the AuthorizationState whenever the Mobile Payments SDK is authorized or deauthorized.

Link to section

Session expiration

Square OAuth access tokens expire after 30 days. After expiration, applications must generate a new OAuth access token using the refresh token received when the authorization was first granted. The response looks like the following:

{ "access_token": "EAAAEL_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n", "token_type": "bearer", "expires_at": "2024-05-15T19:36:00Z", "merchant_id": "TVSNN09QQY609", "refresh_token": "EQAAEInZRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9" }

Square recommends tracking the expires_at value on your server and refreshing the authorization token before it expires. The Mobile Payments SDK checks for an expired authorization token during application startup and initialization and when pairing with a card reader fails. If the SDK detects an expired token, it deauthorizes the Square seller account and invokes the callback registered with setAuthorizationStateChangedCallback with AuthorizationState(isAuthorized = false, isAuthorizationInProgress = false).

Link to section

Deauthorize the Mobile Payments SDK

To deauthorize the Mobile Payments SDK and log out of a seller's Square account, use the Authorization Manager's deauthorize() method. This method provides a completion handler, called when the SDK finishes deauthorizing.

It's a good idea to call this method regularly, when a user logs out of your application or hasn't had any activity within a period of time. This prevents your application from having to track a large number of dangling authorizations.

Link to section

Next steps

After authorizing your application, you're ready to pair a card reader and prepare to start taking payments.