Authorize your Android Application

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.

override fun onResume() {
 super.onResume()
 val authManager = MobilePaymentsSdk.authorizationManager()
 // Authorize and handle authorization successes or failures
 callbackReference = authManager.authorize(accessToken, locationId) { result ->
   when (result) {
     is Success -> {
       finishWithAuthorizedSuccess(result.value)
     }
     is Failure -> {
       when (result.errorCode) {
         NO_NETWORK -> showRetryDialog(result)
         USAGE_ERROR -> showUsageErrorDialog(result)
       }
     }
   }
 }
}

override fun onPause() {
 super.onPause()
 // Remove the callback reference to prevent memory leaks
 callbackReference?.clear()
}

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.

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).

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.

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